配置说明
- 使用 setuptools 生成生产可用的 setup.py，元数据完整，遵循 PyPI 规范。
- 自动读取 README.md 作为长描述（Markdown），不存在时回退到简短描述。
- 合理声明运行时依赖：numpy>=1.24、matplotlib>=3.7；可选功能以 extras_require 提供（seaborn、jupyter）。
- 指定 python_requires=">=3.8"，与依赖的最低 Python 版本保持一致。
- 提供教育、数学与可视化相关的分类信息，并声明 Typing :: Typed（建议在顶级包内放置 py.typed）。
- 包含 notebooks 与类型标注：通过 package_data 捕获 *.ipynb 与 py.typed；如 notebooks 位于更深层目录，建议配合 MANIFEST.in 做递归包含。
- 避免使用废弃参数；不假设许可证类型（未提供 license 时不强行填写）。
代码块
# setup.py
from pathlib import Path
from setuptools import setup, find_packages
PACKAGE_NAME = "edu-math-playground"
DESCRIPTION = (
"教学用数学与可视化示例库，含线代与统计常用函数、"
"Matplotlib/Seaborn 绘图封装、Jupyter 扩展；随附 10 个 "
"Notebook 与类型标注；适合课堂演示与作业发布。"
)
# 读取 README 作为长描述（若不存在则回退到短描述）
this_dir = Path(__file__).parent
readme_path = this_dir / "README.md"
if readme_path.exists():
long_description = readme_path.read_text(encoding="utf-8")
long_description_content_type = "text/markdown"
else:
long_description = DESCRIPTION
long_description_content_type = "text/plain"
setup(
name=PACKAGE_NAME,
version="0.1.0",
description=DESCRIPTION,
long_description=long_description,
long_description_content_type=long_description_content_type,
author="王老师",
author_email="ta@edu.example.com",
# 如有项目主页或文档，可在此添加：url="https://example.com/project",
packages=find_packages(
exclude=("tests", "test", "docs", "examples", "build", "dist")
),
include_package_data=True,
# 建议在顶级包目录放置 py.typed 以表明类型完整性
package_data={
"": ["*.ipynb", "py.typed"],
},
zip_safe=False,
python_requires=">=3.8",
install_requires=[
"numpy>=1.24",
"matplotlib>=3.7",
],
extras_require={
# 可选：使用 Seaborn 绘图相关功能
"plots": ["seaborn>=0.12"],
# 可选：在课堂/Notebook 环境中使用
"notebooks": ["jupyter>=1.0", "jupyterlab>=3"],
# 组合安装：绘图 + Notebook
"all": ["seaborn>=0.12", "jupyter>=1.0", "jupyterlab>=3"],
},
classifiers=[
"Development Status :: 3 - Alpha",
"Intended Audience :: Education",
"Topic :: Education",
"Topic :: Scientific/Engineering :: Mathematics",
"Topic :: Scientific/Engineering :: Visualization",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3 :: Only",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Operating System :: OS Independent",
"Typing :: Typed",
"Natural Language :: Chinese (Simplified)",
],
keywords=[
"education",
"linear algebra",
"statistics",
"matplotlib",
"seaborn",
"jupyter",
"visualization",
"teaching",
],
)
使用指南
-
准备与结构
- 确保 Python 版本 >= 3.8，且已安装 pip 与 build：pip install --upgrade pip build
- 将上述 setup.py 放在项目根目录。
- 顶级包应为可导入的合法 Python 包名（通常使用下划线，如 edu_math_playground），发行名可保留连字符（已设置为 edu-math-playground）。
- 若项目提供类型标注，建议在顶级包目录放置一个空文件 py.typed 以启用消费者的类型检查。
- 若 Notebooks 存放在更深层目录（如 package/notebooks/lesson1/*.ipynb），建议添加 MANIFEST.in 以递归包含：
- 示例 MANIFEST.in：
- recursive-include edu_math_playground/notebooks *.ipynb
-
本地安装
- 开发模式安装（便于调试）：pip install -e ".[notebooks,plots]"
- 普通安装：pip install .
-
构建分发包
- 生成 sdist 与 wheel：python -m build
- 产物位于 dist/ 目录，可用于离线安装：pip install dist/edu_math_playground-0.1.0-py3-none-any.whl
- 注意：实际文件名会按打包后的规范名称生成（发行名中的连字符会规范化）。
-
可选依赖安装
- 启用 Seaborn 绘图：pip install ".[plots]"
- Notebook/课堂环境：pip install ".[notebooks]"
- 全部可选：pip install ".[all]"
-
发布到私有仓库或 PyPI
- 私有仓库：根据企业制品库指引上传 dist/* 包文件。
- PyPI（需 twine）：pip install twine && python -m twine upload dist/*
- 上传前建议完善 README、许可证文件（LICENSE），如为开源项目请在 classifiers 中添加相应的 License 分类。
