Python中利用自定义类实现分层字符串常量与点符号路径自动构建

from collections.abc import Iterable

class Endpoint:
    """
    一个用于组织分层字符串常量（如HTTP端点）的类。
    支持点符号访问子节点，并能自动构建完整的路径字符串。
    """
    def __init__(self, name: str) -> None:
        """
        初始化一个Endpoint实例。

        Args:
            name: 当前端点的名称，例如 'CONFIGURATION'。
        """
        self._name = name
        self._children = {}  # 存储子Endpoint实例的字典
        self._parent = None  # 指向父Endpoint实例的引用

    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:
            # 如果有父节点，则递归获取父节点的路径，并拼接当前名称
            up = f'{str(self._parent)}/'
        else:
            # 如果没有父节点，说明是根节点，路径从当前名称开始
            up = ''
        return f'{up}{self._name.lower()}' # 将名称转为小写，符合URL规范

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

        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) # 创建新的Endpoint实例
        new_endpoint._parent = self                 # 设置新实例的父节点为当前实例
        self._children[endpoint_name] = new_endpoint # 将新实例添加到当前实例的子节点字典中

    def __getattr__(self, _attr: str):
        """
        当通过点符号访问一个不存在的属性时，此方法会被调用。
        它会尝试从_children字典中查找对应的子Endpoint。
        """
        if _attr in self._children:
            return self._children[_attr]
        # 如果_children中也不存在，则按默认方式抛出AttributeError
        return object.__getattribute__(self, _attr)

    def __iadd__(self, endpoint_name: str):
        """
        实现“+=”操作符，提供更简洁的方式来添加子Endpoint。
        例如：config += 'ACTIVE'
        """
        if not isinstance(endpoint_name, str):
            return NotImplemented # 不支持非字符串类型
        self.append_endpoint(endpoint_name)
        return self # 返回自身，支持链式操作

# 创建根Endpoint
endpoints = Endpoint('') # 根路径可以为空字符串，或者根据需要设置为'/'

# 添加一级端点
endpoints += 'CONFIGURATION'
endpoints += 'USERS'

# 添加二级端点
endpoints.CONFIGURATION += 'ACTIVE'
endpoints.CONFIGURATION += 'ARCHIVED'
endpoints.USERS += 'ADMINS'
endpoints.USERS.ADMINS += 'SUPER'

# 添加更多层级
endpoints.CONFIGURATION.ACTIVE += 'LAST_UPDATED'
endpoints.USERS.ADMINS.SUPER += 'ROLES'

# 访问不同层级的路径
print(f"根路径: {str(endpoints)}")
print(f"配置路径: {str(endpoints.CONFIGURATION)}")
print(f"活动配置路径: {str(endpoints.CONFIGURATION.ACTIVE)}")
print(f"最后更新配置路径: {str(endpoints.CONFIGURATION.ACTIVE.LAST_UPDATED)}")
print(f"用户路径: {str(endpoints.USERS)}")
print(f"管理员路径: {str(endpoints.USERS.ADMINS)}")
print(f"超级管理员角色路径: {str(endpoints.USERS.ADMINS.SUPER.ROLES)}")

# 示例输出:
# 根路径: 
# 配置路径: configuration
# 活动配置路径: configuration/active
# 最后更新配置路径: configuration/active/last_updated
# 用户路径: users
# 管理员路径: users/admins
# 超级管理员角色路径: users/admins/super/roles