说明文档
简述
Python迷你工具箱，包含简化的常用工具，旨在帮助脚本快速开发。
它具有调用方式统一、参数简单、向后兼容、实现相对简明、文档相对清晰的特点。
功能描述详见接口文档，常用功能如：执行系统命令、创建/删除文件夹、压缩解压、日志工具、哈希计算、字符加密、邮件发送、钉钉通知、ssh连接、xml解析等。
安装说明
# python版本要求
依赖python3.6+版本, 默认centos7环境yum安装的python3可以使用
# pip仓库配置示例(网速慢建议更换为镜像仓库)
# unix: ~/.pip/pip.conf
# win: %APPDATA%\pip\pip.ini
[global]
index-url = http://pypi.douban.com/simple
trusted-host = pypi.douban.com
# 安装方式
# 完全安装, 建议, 可以使用全部功能
pip3 install mini-toolbox[full]
# 最小化安装, 仅使用原生python3, 可用模块详见源码, 常用模块如下:
# utils/path/extra/logger/hash/archive/mail/pip_list/conifg/ftp
pip3 install mini-toolbox
# 发布地址
Download: https://pypi.org/project/mini-toolbox
Document: https://mini-toolbox.readthedocs.io/zh/latest
调用示例
#!/usr/bin/env python3
# -*- coding:utf-8 -*-
""" mini_toolbox调用示例, unix环境中执行 """
from mini_toolbox.path import mkdirs, pushd
from mini_toolbox.utils import exec_cmd
from mini_toolbox.logger import Logger
# 实例化日志工具
logger = Logger(logger_id='test_lib', to_file=False).logger
# 重建dir2文件夹
mkdirs('dir1/dir2', is_file=False, remake=True)
# 进入dir1/dir2文件夹, 执行结束后返回原路径
with pushd('dir1/dir2'):
# 创建dir3目录, 存在则忽略
mkdirs('dir3/file1', is_file=True)
# 执行`ls -lh`指令, 输出用日志工具打印
rst = exec_cmd('ls -lh')
logger.debug(rst)
# 执行`find .`指令, 输出直接打印
exec_cmd('find .', live=True)
格式规范
文档编写遵循附录中的Google风格文档编写示例
# 迭代说明
1. 版本采用三段式 x.y.z
2. x 表示主版本 - 当产生重大变更或重大里程碑时, x+1, y=z=0
3. y 表示增量版本 - 当z版本大于9时, y+1, z=0
4. z 表示补丁版本 - 当涉及变更时, z+1, z<=9
# 命名大小写
1. 类: 单词首字母大写
2. 全局变量: 字母大写, 下划线分隔
3. 内部函数/方法/对象/变量/模块: 单下划线开头, 小写字母, 下划线分隔
4. 其它函数/方法/对象/变量/模块: 小写字母, 下划线分隔
# 其它约定
1. 格式化 - 使用yapf插件格式化代码 # pip3 install yapf
2. 兼容性 - 相同x版本, 做到向后兼容, 尽量做到向前兼容
3. 更新日志 - 提供y版本的详细变更日志和时间, 做到描述简练、分类正确
4. 实现范围 - 不涉及业务代码, 删除冗余代码/注释, 做到相对独立性和通用性
5. 标点符号 - 代码段中的逗号、冒号、分号全部使用英文符号
5. 类型注释 - 尽量提供代码类型注释
- int/float/str/bool/None
- from typing import Dict, List, Tuple, Optional, Union, Any
打包说明
# 将本地目录作为库安装调试
python3 -m pip install --upgrade pip setuptools wheel
pip3 install -e .[full,docs,build]
# 手动格式化代码
./build.sh format
# 编译和预览文档
./build.sh doc
# 编译全部
./build.sh
# 更新版本及编译 - x/y/z
./build.sh z
附录
Google风格文档编写示例
"""Example Google style docstrings(One line summary).
This module demonstrates documentation as specified by the `Google Python
Style Guide`_. Docstrings may extend over multiple lines. Sections are created
with a section header and a colon followed by a block of indented text.
Example:
Sections support any reStructuredText formatting, including literal
blocks::
$ python example_google.py
>>> print([i for i in example_generator(4)])
[0, 1, 2, 3]
Attributes:
likes_spam: A boolean indicating if we like SPAM or not.
eggs: An integer count of the eggs we have laid.
Args:
param1 (int): The first parameter.
param2 (str): The second parameter.
keys (str): A sequence of strings representing the key of each table \
row to fetch. String keys will be UTF-8 encoded.
Returns:
bool: The return value. True for success, False otherwise.
Raises:
IOError: An error occurred accessing the smalltable.
Todo:
* For module TODOs, need ``sphinx.ext.todo`` extension
* This is colorful block
Note:
This is colorful block
Warning:
This is colorful block
See Also:
This is colorful block. `PEP 484`_ type annotations are supported.
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
"""
Pypi官方打包说明
1. 注册账户, 配置token # https://pypi.org/
# cat ~/.pypirc
[pypi]
username = __token__
password = pypi-xxxxxxxxxxxxxxxxxxxxxxxxxx
2. 安装依赖
python3 -m pip install --upgrade pip setuptools wheel
pip3 install build virtualenv twine
3. 执行打包
python3 -m build
4. 执行上传
python3 -m twine upload --repository pypi dist/*