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("邮件主题", "recipient@qq.com", [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。
Metadata
Release files for xsdk 1.0.17
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xsdk-1.0.17.tar.gz | 58.8 kB | Without provenance | Details for xsdk-1.0.17.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xsdk-1.0.17-py3-none-any.whl | Python 3 | none | any | Details for xsdk-1.0.17-py3-none-any.whl |
Total release size: 119.3 kB
Release files / xsdk-1.0.17.tar.gz
| Download URL | xsdk-1.0.17.tar.gz |
|---|---|
| Size | 58.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
53eb2fd66a14104c8f627ed42981355f8f29575e8ae6ea49ec83d85be9cc8061
|
|
BLAKE2b-256 checksum How to use checksums |
3803cd27dd96ba9b85c15db63c2f39724bdd4258ac4357a9400925868d89176c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / xsdk-1.0.17-py3-none-any.whl
| Download URL | xsdk-1.0.17-py3-none-any.whl |
|---|---|
| Size | 60.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9f61b1dc6ae62059b6c7536cc2d379b6a1855b91c841db37ebb40719396d1213
|
|
BLAKE2b-256 checksum How to use checksums |
55d7fc3a7cad1642724fa269f2d08eda6a7baabf1308f4960e7cf5149664538b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for xsdk 1.0.17
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.