文档字符串和类型提示
原则
- 文档字符串说明操作或使用方法而不是解释理由
- 文档字符串是文档而不是注释
- 在代码中添加注释不是一个好的实践
- 注释表示未能在代码中准确表达想法。如果必解释原因或实现步骤，那证明代码不够好。
- 注释可能产生误导。修改代码往往忘记更新注释，过时的注释和现有代码的逻辑常常令人感到困惑。
- 极少数情况下，无法避免注释，这种情况下可以接受描述性的注释。
- 多写文档字符串，少写注释。
示例
class MyDict(dict):
def update(self, E=None, **F):
"""
D.update([E, ]**F) -> None. Update D from dict/iterable E and F.
If E is present and has a .keys() method, then does: for k in E: D[k] = E[k]
If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v
In either case, this is followed by: for k in F: D[k] = F[k]
>>> d = MyDict()
>>> d.update({1: "one", 2: "two"})
>>> d
{1: "one", 2: "two"}
>>> d.update([(3, "three"), (4, "four")])
>>> d
{1: 'one', 2: 'two', 3: 'three', 4: 'four'}
"""
super().update()
文档字符串会存储在对象的__doc__属性中
def my_function():
"""
Run some computation
"""
return None
print(my_function.__doc__)
# 'Run some computation'
Python3中引入了类型提示
class Point:
def __init__(self, lat, long):
self.lat = lat
self.long = long
def locate(latitude: float, longitude: float) -> Point:
"""
Find an object in the map by its coordinates
"""
return Point(latitude, longitude)
print(locate.__annotations__)
# {'latitude': <class 'float'>, 'longitude': <class 'float'>, 'return': <class 'Point'>}
class Point:
lat: float
long: float
print(Point.__annotations__)
# {'lat': <class 'float'>, 'long': <class 'float'>}
文档字符串和类型提示结合
def data_from_response(response: dict) -> dict:
"""
If the response is OK, return its payload.
- response: a dict like:
{
"status": 200, # <int>
"timestamp": "....", # ISO format string of the current date time
"payload": { ... } # dict with the returned data
}
- Returns a dict like:
{
"data": { ... }
}
- Raises:
- ValueError if the HTTP status is != 200
"""
if response["status"] != 200:
raise ValueError
return {"data": response["payload"]}
详细了解类型提示请查看mypy
