xsdk 1.0.17

Python通用开发工具包

XSDK

Python 通用开发工具包，提供 MySQL、Redis、日志、邮件、HTTP、文件处理、图表生成、腾讯云 COS 等常用功能。

安装

pip install xsdk

配置文件

使用前需要在项目中创建配置文件（推荐放在 conf/ 目录下）。

sys.ini — 系统配置

所有配置统一放在 sys.ini 中，通过不同的 section 区分模块：

[sys_info]
sys_env=DEV                  # 环境标识：DEV / TEST / PROD

[xlog]
log_level=DEBUG              # 全局日志级别（控制台和文件共用）
file_log_flag=Y              # 是否启用文件日志（Y/N）
file_log_path=./             # 日志文件路径
file_log_name=xlog.log       # 日志文件名
console_log_flag=Y           # 是否启用控制台日志（Y/N）

[db_sett]
host=127.0.0.1
port=3306
user=root
password=your_password
timeout=300

可配置多个数据库 section：

[db_business]
host=10.0.0.1
port=3306
user=app_user
password=your_password
timeout=300

[db_analytics]
host=10.0.0.2
port=3306
user=reader
password=your_password
timeout=300

环境变量

以下功能模块需要设置环境变量：

环境变量	用途	格式	示例
XENV_MYSQL	MySQL 连接配置	host:port:user:password[:timeout]	127.0.0.1:3306:root:your_password:6000
XENV_REDIS	Redis 连接地址	redis://host:port/db	redis://127.0.0.1:6379/0
XENV_CONF_FILE	配置文件完整路径	未显式传入 conf_file 时，ConfigReader 从此变量读取	/etc/app/sys.ini
XENV_MAIL_ACCT	QQ 邮箱 SMTP 账号	用户名@授权码 多个用 ^^ 分隔，系统自动拼接 @qq.com	123456@smtp_password
XENV_HTTP_PROXY	HTTP 代理地址	http://user:pwd@host:port 多个用 ^^ 分隔	http://user:pass@proxy:8080

设置方式：

export XENV_MYSQL="127.0.0.1:3306:root:your_password:6000"
export XENV_REDIS="redis://127.0.0.1:6379/0"
export XENV_CONF_FILE="/etc/app/sys.ini"
export XENV_MAIL_ACCT="your_qq_number@your_smtp_password"
export XENV_HTTP_PROXY="http://user:pass@proxy_host:port"

模块说明与使用示例

日志 (xlog)

from xsdk.xlog import Xlog

logger = Xlog.get_logger("conf/sys.ini")
logger.info("应用启动")
logger.error("发生错误", exc_info=True)

• 支持文件日志 + 控制台日志
• 文件日志按天轮转，保留 45 天

MySQL (mysql_client)

from xsdk.mysql_client import MySQLClient

db = MySQLClient.get_instance("conf/sys.ini", conf_section="db_sett")

# 或者通过指定环境变量名初始化
# export XENV_DB_MAIN="127.0.0.1:3306:root:your_password:6000"
db = MySQLClient.get_instance(env_name="XENV_DB_MAIN")

# 不传 conf_file 和 env_name 时，默认读取环境变量 XENV_MYSQL
# export XENV_MYSQL="127.0.0.1:3306:root:your_password:6000"
db = MySQLClient.get_instance()

# 查询
result = db.query("SELECT * FROM users WHERE id = %s", params=(1,))

# 分页查询
page_result = db.query_page("SELECT * FROM users", page_number=1, page_size=20)

# 执行 INSERT/UPDATE/DELETE
db.execute("INSERT INTO users (name) VALUES (%s)", params=("test",))

# 批量插入
db.batch_insert(data_list, "db_name", "table_name")

• 内置连接池（4~64 连接）
• 线程安全，自动重连
• 支持通过环境变量名加载配置，格式为 host:port:user:password[:timeout]
• 取值优先级：env_name > conf_file > 默认环境变量 XENV_MYSQL
• timeout 可省略，默认 6000

Redis (redis_client)

from xsdk.redis_client import RedisClient

# 需要先设置环境变量 XENV_REDIS
RedisClient.set_value("key", "value", timeout=3600)
value = RedisClient.get_value("key")

邮件 (mail_client)

from xsdk.mail_client import MailClient, MailContentData

# 需要先设置环境变量 XENV_MAIL_ACCT
content = MailContentData("标题", "正文内容")
MailClient.send_mail_v2("邮件主题", "[e-mail]", [content])

• 支持 QQ 邮箱 SMTP
• 支持 HTML 内容和附件

HTTP 请求 (http_client)

from xsdk.http_client import HttpClient

response = HttpClient.do_get("https://api.example.com/data")
response = HttpClient.do_post("https://api.example.com/data", body={"key": "value"})

HTTP 代理 (http_proxy)

from xsdk.http_proxy import HttpProxy

# 需要先设置环境变量 XENV_HTTP_PROXY
response = HttpProxy.do_get("https://api.example.com/data")

配置读取 (config_reader)

from xsdk.config_reader import ConfigReader

config = ConfigReader.get_instance("conf/sys.ini")
value = config.get("sys_info", "sys_env")
port = config.get_int("db_sett", "port")

# 环境判断
config.is_dev()   # True if sys_env == DEV
config.is_test()  # True if sys_env == TEST
config.is_prod()  # True if sys_env == PROD

# 也可指定环境变量名，从该变量读取配置文件完整路径
# export XENV_APP_CONF="/etc/app/sys.ini"
config = ConfigReader.get_instance(env_name="XENV_APP_CONF")

# 省略全部参数时，默认从环境变量 XENV_CONF_FILE 读取
# export XENV_CONF_FILE="/etc/app/sys.ini"
config = ConfigReader.get_instance()

• 配置文件路径取值优先级：conf_file > env_name 指定的环境变量 > 默认环境变量 XENV_CONF_FILE

通用工具 (xutil)

from xsdk import Xutil

Xutil.md5_str("hello")           # MD5 哈希
Xutil.clean_str("  HELLO  ")     # 去空格并转小写
Xutil.contains_chinese("你好")    # 检查是否包含中文
Xutil.get_env_param("ENV_KEY")   # 读取环境变量

文件工具 (file_util)

from xsdk import FileUtil

FileUtil.read_file("data.txt")
FileUtil.write_file("output.txt", "content")
FileUtil.delete_file("temp.txt")

CSV 解析 (csv_parser)

from xsdk.csv_parser import CsvParser

# 写入 CSV
CsvParser.write_csv("output.csv", header_list, data_list)

# 读取 CSV（迭代器模式）
for row in CsvParser("data.csv"):
    print(row)

Excel 处理 (excel_util)

from xsdk.excel_util import ExcelUtil

data = ExcelUtil.read_excel_xlrd("data.xls")
ExcelUtil.write_excel("output.xlsx", header_list, data_list)

图表生成 (chart_util)

from xsdk.chart_util import ChartUtil

ChartUtil.gen_bar_chart(x_data, y_data, title="柱状图")
ChartUtil.gen_line_chart(x_data, y_data, title="折线图")

腾讯云 COS (cos_client)

from xsdk.cos_client import CosClient

client = CosClient.get_client("conf/cos.ini", conf_section="cos")
client.upload_file(bucket, local_path, cos_path)
client.download_file(bucket, cos_path, local_path)

网页爬虫 (spider_util)

from xsdk.spider_util import SpiderUtil

SpiderUtil.get_tag_html(html, "div", class_name="content")
SpiderUtil.get_text(html)

对象序列化 (bean_util)

from xsdk.bean_util import BeanUtil, BaseBean

obj = BeanUtil.parse2bean(dict_data, MyBean)
obj_list = BeanUtil.parse2bean_list(dict_list, MyBean)

依赖说明

依赖包	用途
arrow	日期时间处理
requests	HTTP 请求
PyMySQL / DBUtils	MySQL 连接与连接池
redis	Redis 客户端
openpyxl / xlrd / pandas	Excel 读写
matplotlib	图表生成
beautifulsoup4	HTML 解析
cos-python-sdk-v5	腾讯云 COS
pdfplumber / pdfminer	PDF 解析
APScheduler	定时任务

构建与发布

# 安装构建工具
pip install --upgrade build twine

# 构建
python3 -m build

# 发布到 PyPI
./publish_pypi.sh

# 本地安装（开发调试）
pip install dist/xsdk-1.0.1.tar.gz

版本管理（mygit）

本项目托管在本机的裸 Git 服务 mygit（bare repository，位于 /mygit/xsdk.git）。它没有 Web 页面，所有操作均通过 git 命令行完成。

裸 git 使用方式

# 本机克隆
git clone /mygit/xsdk.git

# 其他机器通过 SSH 克隆
git clone henrywuu@100.71.103.125:/mygit/xsdk.git

# 日常开发与普通 git 完全相同
git add <文件>
git commit -m "说明"
git push          # 推送到 mygit
git pull          # 拉取更新

说明：

• 裸仓库只存版本数据、没有工作区，不能直接在 /mygit/xsdk.git 里查看或修改代码，需要克隆到本地操作。
• 没有 Web 界面，浏览历史用 git log、查看某版本文件用 git show <提交>:<路径>。
• 新建其他项目仓库：git init --bare /mygit/项目名.git。
• 服务端已启用大文件限制：单个文件超过 50MB 的推送会被拒绝（pre-receive 钩子强制检查）。大文件请用 .gitignore 排除在版本库之外，确需版本化时考虑 Git LFS。