如何限制Python模块仅对外暴露指定的公开成员

主流Python编辑器（PyCharm、VS Code等）的自动补全逻辑都遵循Python官方的模块接口约定，你可以通过以下几层配置实现需求，按优先级从高到低排列：

1. 定义模块级__all__列表（最通用、效果最确定的方案） #

__all__是Python原生支持的模块公开接口声明，所有主流IDE都会读取这个变量，只有列在__all__内的成员，才会在输入模块名.时出现在补全提示中；同时这个配置也会控制from 模块名 import *时默认导入的成员范围。

示例代码（mymodule.py）：

# ------------------------------
# 以下为内部逻辑成员，不对外暴露
# ------------------------------
def _parse_input(raw_data):
    # 内部数据解析逻辑，不需要使用者感知
    return raw_data.strip()

_INTERNAL_FLAG = 0x1F

def debug_log(msg):
    # 仅模块内部调试用的方法
    print(f"[DEBUG] {msg}")

# ------------------------------
# 以下为指定对外暴露的公开成员
# ------------------------------
def query_data(key: str):
    """对外公开的查询方法"""
    processed_key = _parse_input(key)
    # 核心业务逻辑
    return f"result of {processed_key}"

class DataClient:
    """对外公开的客户端类"""
    pass

DEFAULT_TIMEOUT = 30

# 明确声明所有要对外暴露的成员，注意传入字符串格式的成员名
__all__ = ["query_data", "DataClient", "DEFAULT_TIMEOUT"]

配置完成后，使用者输入mymodule.触发补全时，只会看到query_data、DataClient、DEFAULT_TIMEOUT三个成员，所有内部方法、变量都不会出现在补全列表中。

2. 给内部成员增加单下划线前缀（配合__all__使用效果更好） #

Python的命名约定中，以单下划线开头的模块级成员默认被视为内部私有成员：

• 编辑器补全时会默认隐藏这类成员
• from 模块名 import *时不会导入这类成员
  这个方案不需要维护__all__列表也能实现基础的补全隐藏，但如果模块公开成员很多、内部成员也很多，还是建议搭配__all__明确声明公开接口，避免漏标下划线导致内部成员意外暴露。

注意：这个规则只是约定，不是强制访问限制，如果使用者手动写出mymodule._parse_input依然可以调用，只是补全不会主动提示。

3. 拆分内部逻辑到下划线开头的私有子模块（适合大型模块） #

如果你的模块内部逻辑量很大，可以把所有不对外的实现拆分到以下划线开头的子模块/子文件中，仅在主模块的__init__.py中导入并暴露需要公开的成员，示例目录结构：

mymodule/
├── __init__.py       # 主模块入口，仅放公开成员导出逻辑
├── _core_impl.py     # 下划线开头，存放核心内部实现
├── _utils.py         # 下划线开头，存放内部工具函数
└── exceptions.py     # 不需要隐藏的公开子模块

在__init__.py中仅导入公开成员并配置__all__：

from ._core_impl import query_data, DataClient
from .exceptions import QueryError

DEFAULT_TIMEOUT = 30

__all__ = ["query_data", "DataClient", "QueryError", "DEFAULT_TIMEOUT"]

这种结构下，使用者导入mymodule时，补全列表根本不会展示_core_impl、_utils这两个内部子模块，完全不会干扰使用者的选择。

注意：Python本身没有设计严格的私有成员访问限制，上述方案的核心作用是明确模块的公开接口边界、过滤自动补全的冗余提示，避免使用者误调用不稳定的内部逻辑，不需要追求完全禁止用户访问内部成员——如果使用者刻意要调用带下划线的内部成员，本身就意味着他愿意承担内部逻辑变动带来的兼容性风险。

内容的提问来源于stack exchange，提问作者sina janiloran