Python math-basics 库完整使用指南
一、math-basics 包概述
math-basics是轻量级Python基础数学工具库，基于Python原生math库二次封装，简化基础数学运算、几何计算、进制转换、数列计算、单位换算等常用场景，主打入门友好、语法简洁、无需复杂数学公式编写，主要面向初学者、教学场景、简易数据计算、小型脚本开发。
补充说明：该库非Python标准库，属于第三方小众开源库，专注初等数学范畴，不支持高等数学（微积分、矩阵、线性代数等），复杂科学计算建议使用
numpy/scipy。
二、安装方式
1. 在线pip安装（推荐）
打开终端/CMD/PyCharm终端，执行命令：
# 稳定版安装pipinstallmath-basics# 国内镜像加速（下载慢时使用）pipinstallmath-basics-ihttps://pypi.tuna.tsinghua.edu.cn/simple2. 离线安装
- 前往 PyPI math-basics 下载
.whl离线包； - 进入文件所在目录，执行：
pipinstallmath_basics-xxx.whl3. 验证安装
Python交互式环境执行导入，无报错即安装成功：
importmath_basics三、核心功能、语法与通用参数
（一）整体模块结构
库核心分为6大功能模块，所有函数调用格式统一：
# 标准调用语法importmath_basics math_basics.函数名(参数列表)（二）六大核心功能分类 + 常用函数、参数详解
1. 基础算术运算（Arithmetic）
简化四则运算、取余、绝对值、最值、阶乘、幂运算。
| 函数 | 作用 | 参数说明 | 返回值 |
|---|---|---|---|
add(a,b) | 两数相加 | a/b：int/float，运算数字 | 计算结果 |
sub(a,b) | 两数相减 | a/b：int/float | 计算结果 |
mul(a,b) | 两数相乘 | a/b：int/float | 计算结果 |
div(a,b) | 两数除法 | a/b：int/float，b不能为0 | 浮点型商 |
factorial(n) | 计算阶乘 | n：非负整数 | 阶乘结果 |
abs_num(x) | 绝对值 | x：int/float | 非负数值 |
2. 指数与对数（Exponent & Log）
封装平方、立方、开方、自然对数、常用对数。
| 函数 | 作用 | 参数 |
|---|---|---|
square(x) | 计算平方 | x：int/float |
cube(x) | 计算立方 | x：int/float |
sqrt_num(x) | 算术平方根 | x ≥ 0，负数报错 |
log10_num(x) | 以10为底对数 | x > 0 |
ln_num(x) | 自然对数(ln) | x > 0 |
3. 三角函数（Trigonometry）
默认参数单位：角度（°）（原生math库为弧度，这是本库最大特色）
| 函数 | 作用 | 参数 |
|---|---|---|
sin_deg(deg) | 正弦（角度） | deg：角度值 |
cos_deg(deg) | 余弦（角度） | deg：角度值 |
tan_deg(deg) | 正切（角度） | deg：角度值 |
rad2deg(rad) | 弧度转角度 | rad：弧度值 |
deg2rad(deg) | 角度转弧度 | deg：角度值 |
4. 几何计算（Geometry）
平面图形周长、面积计算（三角形、矩形、圆形、梯形等）
| 函数 | 作用 | 参数 |
|---|---|---|
circle_area(r) | 圆面积 | r：半径，r>0 |
circle_peri(r) | 圆周长 | r：半径 |
rect_area(w,h) | 矩形面积 | w宽、h高 |
triangle_area(a,b,c) | 海伦公式求三角面积 | 三边长度（满足三角不等式） |
5. 进制转换（Base Convert）
十进制、二进制、八进制、十六进制互转，返回字符串
| 函数 | 作用 | 参数 |
|---|---|---|
dec2bin(n) | 十进制 → 二进制 | n：十进制整数 |
dec2oct(n) | 十进制 → 八进制 | n：十进制整数 |
dec2hex(n) | 十进制 → 十六进制 | n：十进制整数 |
bin2dec(s) | 二进制字符串 → 十进制 | s：二进制字符串 |
6. 数列与统计（Sequence & Stats）
求和、平均数、等差数列、最大公约数、最小公倍数
| 函数 | 作用 | 参数 |
|---|---|---|
avg(list_data) | 列表平均值 | list_data：数字列表 |
sum_list(list_data) | 列表求和 | list_data：数字列表 |
gcd(a,b) | 最大公约数 | a、b：正整数 |
lcm(a,b) | 最小公倍数 | a、b：正整数 |
（三）通用规则
- 数值参数支持
int/float，部分函数（阶乘、进制、公约数）仅支持整数； - 所有几何、开方函数要求输入正数，负数直接抛出异常；
- 三角函数输入为角度，区别于原生
math库（弧度）； - 进制转换函数输入为数字/字符串，输出统一为字符串。
四、8个实战应用案例（可直接运行）
案例1：基础四则运算 + 阶乘计算
需求：计算 12+34、90-23、8×7、100÷4，以及 8的阶乘
importmath_basics# 四则运算print("加法：",math_basics.add(12,34))print("减法：",math_basics.sub(90,23))print("乘法：",math_basics.mul(8,7))print("除法：",math_basics.div(100,4))# 阶乘print("8的阶乘：",math_basics.factorial(8))案例2：平方、立方与平方根计算
需求：计算 16的平方、5的立方、81的算术平方根
importmath_basicsprint("16平方：",math_basics.square(16))print("5立方：",math_basics.cube(5))print("81平方根：",math_basics.sqrt_num(81))案例3：角度制三角函数计算
需求：计算 30°、45°、90° 的正弦、余弦值
importmath_basicsprint("30°正弦：",math_basics.sin_deg(30))print("45°余弦：",math_basics.cos_deg(45))print("90°正切：",math_basics.tan_deg(90))案例4：平面几何（圆+矩形面积周长）
需求：半径为5的圆、长8宽6的矩形，分别计算面积和周长
importmath_basics# 圆形r=5print("圆面积：",math_basics.circle_area(r))print("圆周长：",math_basics.circle_peri(r))# 矩形w,h=8,6print("矩形面积：",math_basics.rect_area(w,h))案例5：十进制与多进制互转
需求：将十进制255转二/八/十六进制；二进制1010转回十进制
importmath_basics num=255print("十进制255 → 二进制：",math_basics.dec2bin(num))print("十进制255 → 八进制：",math_basics.dec2oct(num))print("十进制255 → 十六进制：",math_basics.dec2hex(num))bin_str="1010"print("二进制1010 → 十进制：",math_basics.bin2dec(bin_str))案例6：统计计算（列表求和、平均值）
需求：对成绩列表[85,92,78,90,88]求和、求平均分
importmath_basics score=[85,92,78,90,88]print("总分：",math_basics.sum_list(score))print("平均分：",math_basics.avg(score))案例7：最大公约数 & 最小公倍数
需求：计算 24 和 36 的最大公约数、最小公倍数
importmath_basics a,b=24,36print("最大公约数：",math_basics.gcd(a,b))print("最小公倍数：",math_basics.lcm(a,b))案例8：综合应用题（直角三角形计算）
需求：直角三角形两直角边为 6、8，求斜边、面积、锐角正弦值
importmath_basics# 直角边side1,side2=6,8# 求斜边（勾股定理：开方(平方和)）hypotenuse=math_basics.sqrt_num(math_basics.square(side1)+math_basics.square(side2))# 三角形面积area=math_basics.triangle_area(side1,side2,hypotenuse)print("斜边长度：",hypotenuse)print("三角形面积：",area)五、常见错误及解决方案
1. 导入报错：ModuleNotFoundError
错误现象：No module named 'math_basics'
- 原因：未安装库、安装环境与运行环境不匹配（多Python版本/虚拟环境）
- 解决：重新执行
pip install math-basics，确认pip对应当前Python解释器。
2. 除法报错：ZeroDivisionError
错误现象：除法函数分母为0
math_basics.div(10,0)# 报错- 原因：除数不能为0
- 解决：代码增加判断，过滤分母为0的场景。
3. 开方/几何函数负数报错
错误现象：ValueError: input must be positive
math_basics.sqrt_num(-9)math_basics.circle_area(-3)- 原因：半径、被开方数不能为负数
- 解决：前置校验输入数值 ≥ 0。
4. 阶乘传入小数/负数报错
错误现象：ValueError: factorial only support non-negative integer
math_basics.factorial(5.5)math_basics.factorial(-2)- 原因：阶乘仅支持非负整数
- 解决：强制转换为整数，或判断数值合法性。
5. 进制转换传入非数字字符串报错
错误现象：进制转换传入非法字符
math_basics.bin2dec("1234")# 二进制不能出现2、3、4- 原因：进制字符串格式非法
- 解决：保证二进制仅含
0/1，八进制0-7，十六进制0-9/a-f。
6. 三角函数混淆角度/弧度
错误现象：结果和预期不符
- 原因：原生
math用弧度，math-basics三角函数默认角度，混用导致计算错误 - 解决：角度计算直接用
sin_deg/cos_deg，需要弧度再用deg2rad转换。
7. 列表统计函数传入非列表类型
错误现象：TypeError: input must be list
math_basics.avg(90)# 传入数字而非列表- 原因：
sum_list/avg要求入参为数字列表 - 解决：将单值/多值封装为列表
[90]。
六、使用注意事项
适用场景限制
仅用于初等数学，不支持矩阵、微积分、复数、大数据科学计算，复杂场景改用numpy/sympy。精度问题
底层基于Python浮点运算，小数运算存在微小精度误差，金融、高精度计算不建议使用。版本兼容
兼容 Python3.6+，不支持Python2。函数命名区分
本库函数均带后缀（_num/_deg），和原生math函数名区分，不要混用。参数类型严格性
公约数、阶乘、进制转换强依赖整数，浮点型会直接报错，使用前建议类型校验。大型项目不推荐
该库为小众封装库，维护频率低，企业级开发优先使用Python标准库math。
《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。
