Python中利用点表示法构建与管理分层字符串常量教程

class EndpointClass:
    class CONFIGURATION:
        ACTIVE = '/configuration/active'

from collections.abc import Iterable

class Endpoint:
    """
    一个用于组织分层字符串常量的类，支持点表示法访问和自动路径拼接。
    """
    def __init__(self, name: str) -> None:
        """
        初始化一个Endpoint实例。

        Args:
            name: 当前端点的名称，例如 'CONFIGURATION' 或 'ACTIVE'。
        """
        self._name = name  # 当前节点的名称
        self._children = {} # 存储子节点，键为子节点名称，值为子Endpoint实例
        self._parent = None # 指向父节点，用于路径回溯

    def __dir__(self) -> Iterable[str]:
        """
        定制当调用 dir() 或 IDE 自动补全时返回的属性列表。
        这使得子节点可以通过点表示法被发现。
        """
        cls_attrs = object.__dir__(self)
        # 将子节点的名称添加到可发现的属性列表中
        return [n for n in self._children] + cls_attrs

    def __repr__(self) -> str:
        """
        提供一个清晰的实例表示，主要用于调试。
        """
        return f'<Endpoint({self._name!r})>'

    def __str__(self) -> str:
        """
        核心方法：递归地构建完整的端点路径字符串。
        如果存在父节点，则会先调用父节点的 __str__ 方法，然后拼接当前节点的名称。
        """
        if self._parent:
            # 递归调用父节点的 __str__ 方法，并在后面加上 '/'
            up = f'{str(self._parent)}/'
        else:
            # 如果没有父节点，则路径从根开始
            up = ''
        # 将当前节点的名称转换为小写并拼接
        return f'{up}{self._name.lower()}'

    def append_endpoint(self, endpoint_name: str):
        """
        向当前端点添加一个子端点。

        Args:
            endpoint_name: 要添加的子端点的名称。

        Raises:
            KeyError: 如果具有相同名称（不区分大小写）的子端点已存在。
        """
        # 检查是否已存在同名（不区分大小写）的子端点
        if any(c.lower()==endpoint_name.lower() for c in self._children):
            raise KeyError(f'A sub-endpoint {endpoint_name!r} already exists.')

        # 创建新的子端点实例
        new_endpoint = self.__class__(endpoint_name)
        new_endpoint._parent = self # 设置新子端点的父节点为当前实例
        self._children[endpoint_name] = new_endpoint # 将子端点添加到子节点字典中

    def __getattr__(self, _attr: str):
        """
        当尝试访问不存在的属性时调用。
        如果请求的属性是子节点之一，则返回对应的子Endpoint实例。
        """
        if _attr in self._children:
            return self._children[_attr]
        # 如果不是子节点，则按默认方式抛出 AttributeError
        return object.__getattribute__(self, _attr)

    def __iadd__(self, endpoint_name: str):
        """
        实现 += 运算符，允许使用 'endpoint += "CHILD"' 的语法添加子端点。
        """
        if not isinstance(endpoint_name, str):
            return NotImplemented
        self.append_endpoint(endpoint_name)
        return self

# 创建根端点
config = Endpoint('CONFIGURATION')

# 使用 += 运算符添加子端点
config += 'ACTIVE'         # 'ACTIVE' 将出现在 IDE 的自动补全列表中
config.ACTIVE += 'LAST'    # 可以在子端点上继续添加更深层的子端点

config += 'INACTIVE'
config.INACTIVE += 'HISTORY'
config.INACTIVE.HISTORY += 'Y2020'
config.INACTIVE.HISTORY += 'Y2021'
config.INACTIVE.HISTORY += 'Y2022'
config.INACTIVE.HISTORY += 'Y2023'

# 访问并打印完整的路径字符串
print(str(config))
# 输出: configuration

print(str(config.ACTIVE))
# 输出: configuration/active

print(str(config.ACTIVE.LAST))
# 输出: configuration/active/last

print(str(config.INACTIVE.HISTORY.Y2023))
# 输出: configuration/inactive/history/y2023

# 尝试添加重复的子端点（不区分大小写）会抛出 KeyError
try:
    config += 'active'
except KeyError as e:
    print(f"Error: {e}")
# 输出: Error: 'A sub-endpoint 'active' already exists.'