def calculate_discount(price: float, discount_rate: float) -> float:
"""计算折扣后的价格。
Args:
price: 原价，必须大于0
discount_rate: 折扣率，范围0-1
Returns:
折扣后的价格
Raises:
ValueError: 当price <= 0或discount_rate不在0-1范围时
Example:
>>> calculate_discount(100, 0.2)
80.0
"""
if price <= 0:
raise ValueError("价格必须大于0")
if not 0 <= discount_rate <= 1:
raise ValueError("折扣率必须在0-1之间")
return price * (1 - discount_rate)

def find_maximum(array):
"""
找到数组中的最大值。
Parameters
----------
array : list or tuple
包含数值的序列
Returns
-------
float or int
数组中的最大值
Examples
--------
>>> find_maximum([1, 5, 3, 9, 2])
9
"""
return max(array)

def connect_database(host, port=5432, user=None, password=None):
"""连接到数据库。
:param host: 数据库主机地址
:type host: str
:param port: 端口号，默认5432
:type port: int
:param user: 用户名
:type user: str
:param password: 密码
:type password: str
:return: 数据库连接对象
:rtype: Connection
:raises ConnectionError: 连接失败时抛出
"""
pass

from typing import List, Dict, Optional, Tuple, Union, Any
基础类型
def greet(name: str) -> str:
return f"Hello, {name}"
容器类型
def process_items(items: List[int]) -> Dict[str, int]:
return {"count": len(items), "sum": sum(items)}
可选类型
def find_user(user_id: int) -> Optional[Dict[str, Any]]:
...
联合类型
def parse_value(value: Union[str, int, float]) -> float:
return float(value)
元组类型
def get_coordinates() -> Tuple[float, float]:
return (0.0, 0.0)
任意类型
def log_message(message: Any) -> None:
print(message)

from typing import TypeVar, Generic, Protocol
类型变量
T = TypeVar('T')
class Stack(Generic[T]):
def __init__(self) -> None:
self._items: List[T] = []
def push(self, item: T) -> None:
self._items.append(item)
def pop(self) -> T:
return self._items.pop()
协议（接口）
class Drawable(Protocol):
def draw(self) -> None:
...
def render(shape: Drawable) -> None:
shape.draw()

# 安装mypy
pip install mypy
运行类型检查
mypy your_module.py
严格模式
mypy --strict your_module.py

# 安装
pip install sphinx sphinx-rtd-theme
初始化
cd docs
sphinx-quickstart
回答提示问题

# conf.py
project = 'my-package'
copyright = '2026, Your Name'
author = 'Your Name'
release = '1.0.0'
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',  # Google/NumPy风格docstring
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
]
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

# 生成API文档
sphinx-apidoc -o docs/source ../src
构建HTML文档
make html
预览
cd build/html
python -m http.server 8000

docs/
├── source/
│   ├── conf.py
│   ├── index.rst          # 首页
│   ├── api.rst            # API文档
│   ├── guide.rst          # 使用指南
│   └── _static/           # 静态文件
├── Makefile
└── requirements.txt

.. index.rst
Welcome to my-package's documentation!
======================================
.. toctree::
:maxdepth: 2
:caption: Contents:
guide
api
changelog
Indices and tables
==================

●:ref:genindex

●:ref:modindex

●:ref:search

# 安装
pip install mkdocs mkdocs-material
初始化
mkdocs new my-package-docs
cd my-package-docs
配置 mkdocs.yml
site_name: my-package
theme:
name: material
palette:
primary: blue
accent: indigo
nav:
- Home: index.md
- Guide:
- Installation: guide/installation.md
- Usage: guide/usage.md
- API:
- Core: api/core.md
- Utils: api/utils.md
- Changelog: changelog.md
plugins:
- search
- mkdocstrings

<!-- index.md -->
my-package
一个强大的Python工具库。
快速开始

from my_package import hello

特性

●✅ 简单易用

●✅ 类型安全

●✅ 高性能

# 预览
mkdocs serve
构建
mkdocs build
部署到GitHub Pages
mkdocs gh-deploy

"""
my_package - 一个Python工具库
这个包提供了常用的数据处理和工具函数。
Example:
>>> from my_package import utils
>>> utils.add(1, 2)
3
Attributes:
__version__ (str): 版本号
"""
__version__ = '1.0.0'

class Database:
"""数据库连接类。
提供数据库连接、查询、事务管理等功能。
Attributes:
host (str): 数据库主机
port (int): 端口号
connection (Connection): 连接对象
Example:
>>> db = Database(host='localhost', port=5432)
>>> db.connect()
>>> db.execute('SELECT * FROM users')
"""
def __init__(self, host: str, port: int = 5432):
"""初始化数据库连接。
Args:
host: 数据库主机地址
port: 端口号，默认5432
"""
self.host = host
self.port = port
self.connection = None

def process_data(data: List[Dict]) -> List[Dict]:
"""处理数据。
对输入数据进行清洗、转换和验证。
Args:
data: 原始数据列表，每个元素是一个字典
Returns:
处理后的数据列表
Raises:
ValidationError: 数据验证失败时抛出
Note:
处理过程包括：
1. 去除空值
2. 类型转换
3. 数据验证
"""
pass

# ✅ 好的行内注释
result = calculate(x)  # 计算x的平方
❌ 不好的行内注释
result = calculate(x)  # 调用calculate函数
❌ 不必要的注释
x = 1  # x等于1

# 项目名称
[
](https://pypi.org/project/my-package/)
[
](https://pypi.org/project/my-package/)
[
](LICENSE)
简短描述项目用途。
特性

●特性1

●特性2

●特性3


安装

快速开始

from my_package import hello

文档
完整文档请访问：[https://my-package.readthedocs.io](https://my-package.readthedocs.io)
示例

from my_package import Example

开发

贡献
欢迎提交Issue和Pull Request！
许可证
MIT License - 详见 [LICENSE](LICENSE) 文件。

[](https://pypi.org/project/my-package/)
[
](https://pypi.org/project/my-package/)
[
](LICENSE)
[
](https://github.com/yourname/my-package/actions)
[
](https://codecov.io/gh/yourname/my-package)
[
](https://my-package.readthedocs.io/)

# Changelog
所有重要变更将记录在此文件中。
格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)。
版本遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
[未发布]
新增

●待发布功能


[1.0.0] - 2026-05-26
新增

●初始版本发布

●支持基本数据处理功能

●添加命令行工具


变更

●优化性能，提升50%


修复

●修复内存泄漏问题

●修复Unicode编码错误


删除

●移除已弃用的API


[0.1.0] - 2026-05-01
新增

●项目初始化

# ✅ 好的注释
计算两个向量的点积
def dot_product(a, b):
...
✅ 好的docstring
def add(a: int, b: int) -> int:
"""返回两个整数的和。
Args:
a: 第一个整数
b: 第二个整数
Returns:
两个整数的和
"""
return a + b
❌ 不好的注释
a加b
def add(a, b):
...
❌ 不必要的注释
x = 1  # x等于1

📚 推荐阅读

KEYWORDS

IL, Python, python, 函数, 变量

💡 如果你觉得这篇文章有帮助，请点个在看，分享给更多需要的人！

📝 关注我，获取更多实用干货～

🤝 有问题欢迎评论区留言交流！