Skip to main content

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)

Source distribution for xsdk 1.0.17
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)

Table of built distributions (wheels) for xsdk 1.0.17
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page