doxxie

doxxie 是一个 mypy 插件，它输出mypy-typed Python库的真实公共API。 doxxie 的输出可以提交到源控制，并通过 CI作业 进行验证，以确保对公共API的更改是有意为之并已记录。

doxxie 挖掘库的公共API，并递归地挖掘出由公共属性和函数暴露的所有类型，直到达到真实的公共API。

安装

从PyPI安装

$ pip install doxxie

使用方法

将 doxxie 添加到 mypy 配置文件 的插件部分

[mypy]
files = mylib/
plugins = doxxie

然后使用指定包含哪些模块的环境变量运行mypy

$ DOXXIE_INCLUDES=mylib mypy --no-incremental

将输出一个包含 mylib 公共API的 .public_api 文件。

注意： 由于 doxxie 无法访问mypy的缓存类型信息，因此需要使用 --no-incremental 标志。

输出

doxxie 输出一个包含指定模块所有公共变量的 .public_api 文件。

示例

有关以下代码的示例，请参阅 docs/example

考虑以下Python库 lib

lib/
├── __init__.py
├── api/
│   └── __init__.py
└── _internal/
    └── __init__.py

# api/__init__.py
from lib._internal import LeakedPrivate, Private

class Public:
    def __init__(self):
        self.public_attr: int = 5
        self.public_leak: LeakedPrivate = LeakedPrivate()
        self._private: Private = Private()

    def public_method(self) -> None:
        pass

    def _private_method(self) -> str:
        return "hi"

# _internal/__init__.py
class LeakedPrivate:
    def public_method(self) -> None:
        pass

class Private:
    pass

运行 DOXXIE_INCLUDES=pkg.api DOXXIE_EXCLUDES=pkg._internal mypy 将输出以下内容到 .public_api

{'lib.Private': {'bases': ['builtins.object'],
                 'mro': ['lib.Private', 'builtins.object']},
 'lib.Private.public_method': {'arg_kinds': [0],
                               'arg_names': ['self'],
                               'type': {'arg_types': ['lib.Private'],
                                        'ret_type': {'.class': 'NoneType'}}},
 'lib._internal.LeakedPrivate': {'bases': ['builtins.object'],
                                 'mro': ['lib._internal.LeakedPrivate',
                                         'builtins.object']},
 'lib._internal.LeakedPrivate.public_method': {'arg_kinds': [0],
                                               'arg_names': ['self'],
                                               'type': {'arg_types': ['lib._internal.LeakedPrivate'],
                                                        'ret_type': {'.class': 'NoneType'}}},
 'lib.api.Public': {'bases': ['builtins.object'],
                    'mro': ['lib.api.Public', 'builtins.object']},
 'lib.api.Public.__init__': {'arg_kinds': [0],
                             'arg_names': ['self'],
                             'type': {}},
 'lib.api.Public.public_attr': {'type': 'builtins.int'},
 'lib.api.Public.public_leak': {'type': 'lib._internal.LeakedPrivate'},
 'lib.api.Public.public_method': {'arg_kinds': [0],
                                  'arg_names': ['self'],
                                  'type': {'arg_types': ['lib.api.Public'],
                                           'ret_type': {'.class': 'NoneType'}}}}

配置

所有配置都通过环境变量完成。

• DOXXIE_INCLUDES：要包含在公共API中的模块的逗号分隔列表。只有提供模块下的项目才会包含在公共API输出中。
  • 示例： "mod1,mod2"
  • 默认值：""（默认情况下不包含任何内容）
• DOXXIE_EXCLUDES：从公共API中排除的模块的逗号分隔列表。这些模块最初将被忽略，但来自这些模块的项目可能会通过公共API公开并包含在输出中。
  • 示例："mod1.internal,mod1.vendor"
  • 默认：""
• DOXXIE_OUTFILE：输出结果的文件
  • 示例："my_public_api"
  • 默认：".public_api"
• DOXXIE_DERIVE_OUTFILE：输出包含在公共API中的每个项目的推导结果。此输出可以用来显示导致项目公开的属性链。
  • 示例："public_api_derivation"
  • 默认：禁用
• DOXXIE_DEBUG：启用调试日志
  • 示例："1"
  • 默认：禁用

CI作业

doxxie可用于帮助避免对库的公共API进行意外的更改。为此，将.public_api文件（由doxxie生成）检入源代码控制，并强制使用CI作业始终提交对它的更改。

GitHub工作流程

name: CI
on:
  pull_request:
  push:
    branches:
      - main
jobs:
  check_api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: '3.9'
      - name: install dependencies
        run: pip install mypy doxxie
      - run: DOXXIE_INCLUDES=doxxie DOXXIE_OUTFILE=.public_api_delta mypy --no-incremental
      - run: diff .public_api .public_api_delta