如何标记Python Enum的.value为不稳定实现细节？

针对你不想让API使用者依赖Enum的.value属性（将其视为不稳定实现细节）的需求，这里有几种常规的技术方案：

1. 重写__getattribute__拦截.value访问 #

通过重写枚举类的__getattribute__方法，当用户尝试访问.value时抛出警告或错误，明确引导他们使用你暴露的公开属性（比如.surface_gravity）。

示例代码：

from enum import Enum
import warnings

class Planet(Enum):
    MERCURY = (3.303e+23, 2.4397e6)
    VENUS   = (4.869e+24, 6.0518e6)
    EARTH   = (5.976e+24, 6.37814e6)
    MARS    = (6.421e+23, 3.3972e6)
    JUPITER = (1.9e+27,   7.1492e7)
    SATURN  = (5.688e+26, 6.0268e7)
    URANUS  = (8.686e+25, 2.5559e7)
    NEPTUNE = (1.024e+26, 2.4746e7)

    def __init__(self, mass, radius):
        self.mass = mass
        self.radius = radius

    @property
    def surface_gravity(self):
        G = 6.67300E-11
        return G * self.mass / (self.radius ** 2)

    def __getattribute__(self, name):
        if name == 'value':
            warnings.warn(
                ".value是实现细节，请使用.surface_gravity等公开属性",
                DeprecationWarning,
                stacklevel=2
            )
        return super().__getattribute__(name)

效果：用户访问.value时会收到警告，但仍能拿到值；如果想彻底禁止访问，可以抛出AttributeError替代警告。

2. 自定义元类隐藏.value #

通过自定义Enum的元类，修改枚举成员的.value属性的可见性，比如将其设为私有属性，彻底禁止外部访问。

示例代码：

from enum import Enum, EnumMeta

class HiddenValueEnumMeta(EnumMeta):
    def __getattribute__(cls, name):
        member = super().__getattribute__(name)
        if isinstance(member, Enum):
            # 将原.value转存为私有属性
            object.__setattr__(member, '_value', member.value)
            # 删除公开的.value属性
            del member.value
        return member

class Planet(Enum, metaclass=HiddenValueEnumMeta):
    MERCURY = (3.303e+23, 2.4397e6)
    VENUS   = (4.869e+24, 6.0518e6)
    EARTH   = (5.976e+24, 6.37814e6)
    MARS    = (6.421e+23, 3.3972e6)
    JUPITER = (1.9e+27,   7.1492e7)
    SATURN  = (5.688e+26, 6.0268e7)
    URANUS  = (8.686e+25, 2.5559e7)
    NEPTUNE = (1.024e+26, 2.4746e7)

    def __init__(self, mass, radius):
        self.mass = mass
        self.radius = radius

    @property
    def surface_gravity(self):
        G = 6.67300E-11
        return G * self.mass / (self.radius ** 2)

效果：用户直接访问Planet.EARTH.value会抛出AttributeError，内部可通过._value访问原数据，完全隔离实现细节。

3. 封装内部数据，避免直接使用元组作为枚举值 #

不直接用元组作为枚举值，而是用私有内部类封装mass和radius，将这个类的实例作为枚举值。这样即使用户拿到.value，也无法直接获取原始元组，只能通过你允许的方式访问数据。

示例代码：

from enum import Enum

class _PlanetData:
    """私有内部类，封装行星数据"""
    def __init__(self, mass, radius):
        self._mass = mass
        self._radius = radius

class Planet(Enum):
    MERCURY = _PlanetData(3.303e+23, 2.4397e6)
    VENUS   = _PlanetData(4.869e+24, 6.0518e6)
    EARTH   = _PlanetData(5.976e+24, 6.37814e6)
    MARS    = _PlanetData(6.421e+23, 3.3972e6)
    JUPITER = _PlanetData(1.9e+27,   7.1492e7)
    SATURN  = _PlanetData(5.688e+26, 6.0268e7)
    URANUS  = _PlanetData(8.686e+25, 2.5559e7)
    NEPTUNE = _PlanetData(1.024e+26, 2.4746e7)

    def __init__(self, data):
        self.mass = data._mass
        self.radius = data._radius

    @property
    def surface_gravity(self):
        G = 6.67300E-11
        return G * self.mass / (self.radius ** 2)

效果：用户访问Planet.EARTH.value得到的是_PlanetData实例，而这个类是私有的，无法直接使用其内部属性，只能通过你暴露的.mass、.radius、.surface_gravity访问数据。

补充建议 #

可以将上述技术方案与你原来的docstring注释结合使用，多维度强化API的使用规范，降低用户误用的概率。

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