199-540327-为自定义模块添加详细文档_pydoc.sy.md

show	version	enable_checker
step	1.0	true

自定义模块文档(pydoc)

回忆

• 上次了解了包(package)
• 一个文件夹初始化(initial)了之后就是一个包(package)
• 包(package)里面可以有更细化的包
• 模块(module)
  • 可以是一个py文件
  • 也可以是一个包
  • 包一定要有初始化
    • __init__.py
• 导入包的时候
  • 依次执行__init__.py
• 包和模块复杂了之后没有文档就很无从下手
• 可以给我们的模块做文档么？🤔

观察

• 首先观察fractions模块
  • 在游乐场里

• 查看文档

源程序

• 这些注释是写到程序源文件中的
  • 在源文件头部的三引号注释当中
• 我们也去写oeasy.py

写文档

• 然后去游乐场导入试试

• 再去定一个变量

变量

• 修改后需要刷新已经导入的oeasy模块

帮助

• 好像确实有了新的一个DATA
• 再去定义一个函数

重写模块

• 注意在函数下面有三引号的注释
• 注意引号缩进的位置

• 刷新

再次导入观察

• 确实有函数
• 也有函数的文档了
• 继续深入

__doc__

• oeasy是一个模块类的变量

• 那么模块里面的变量、函数可以访问么？

访问模块中的变量

• 那么oeasy这个模块的内存地址是多少？

内存地址

• 为什么oeasy.o的内存地址比oeasy模块的还小那么多呢？
• 回忆一下小数值池
  • range(-5,256)
• 如果我们让oeasy.o的数值离开小数值池

新的整型变量

• 然后让oeasy.o指向这个地址

• 每次重新赋值都会重新分配内存空间

• 会分配一个28字节的内存空间
• 模块内的函数又如何呢？

函数

• 这里面有三类对象
  • 模块
  • 模块中的整型变量
  • 模块中的函数

• 模块中的函数是一个
  • function类型的对象
  • 在内存中申请了一定大小内存空间
  • 变量指向内存中的地址

函数调用

• 导入模块之后
• 可以调用(call)模块中的函数(function)

• 可以把模块中的函数名赋给一个变量f
• 这个变量f指向fun所在的地址
• f仍然可以被调用
• 函数内部的局部变量可以被调用么？

定义函数中的局部变量

• 尝试引用

• 函数变量没有这个属性(attribute)
• 函数到底有些什么属性(attribute)呢？

__dir__属性

• 这个函数对象有很多属性
• __dir__可以查看这些属性 __dir__是什么呢？

• 一个内建的函数
• 可以查询对象的属性
• 对象类型可以是
  • 各种变量类型
  • 函数类型
  • 模块类型

• 还有什么比较熟悉的属性呢？

__globals__属性

• 比如 __globals__

• 可以查到函数的父级模块的全局(globals)变量
• 父级模块是谁呢？

• 还有什么属性呢？

__doc__属性

• 这些就是用三引号引起来的自定义帮助
• 可以被pydoc访问到的
• 模块中的变量可以有帮助么？

• 这个相当于
  • help(int)
  • 查询变量类型的帮助
• 这就是我们了解到的自定义帮助
  • 可以在游乐场使用
  • 可以生成帮助网页么？

生成网页

• 可以生成网页

• doc写作有什么规矩么？

doc惯例

• 大写首字母
• 第一行是摘要
• 第二行空着
• 第三行有缩进
• 写一些惯用例子
• 这其实来自于一条pep

pep

• 2001年的时候就开立规矩了

编写

• 查看

总结

• 我们这次研究了文档
• 模块本身有三种对象
  • 模块
  • 变量
  • 函数

• 可以用三引号来写文档
• 文档被写在__doc__这个字符串类型的属性里面
• 可以用help和网页的方式查看
• 模块的位置位于/usr/lib/python3.8/下面
• 我可以定一个自己的类库路径么？🤔
• 我们下次再说👋