access-control-async 0.2.5__py3-none-any.whl

access_control/__init__.py

@@ -0,0 +1,12 @@
+"""
+访问控制模块。
+"""
+
+from .resource_manager import (
+    ResourceManager,
+    ControlCode, AccessCode, Code, Resource
+)
+
+from .file_backed_resource_manager import FileBackedResourceManager
+
+__version__ = "0.2.5"

access_control/exceptions.py

@@ -0,0 +1,18 @@
+"""
+异常
+"""
+
+class ResourceManagerError(Exception):
+    """
+    与 ResourceManager 有关的错误。
+    """
+
+class PermissionInsufficient(ResourceManagerError):
+    """
+    所使用的控制/访问码的权限不足（控制/访问码不存在）。
+    """
+
+class CodeExistError(ResourceManagerError):
+    """
+    若控制码/访问码重复。
+    """

access_control/file_backed_resource_manager.py

@@ -0,0 +1,195 @@
+"""
+class: FileBackedResourceManager
+"""
+
+import asyncio
+from collections.abc import Callable, Coroutine
+import os
+import pickle
+from typing import Generic, Optional, override
+from uuid import uuid4
+
+import aiofiles
+import aiofiles.os
+from pathvalidate import ValidationError, is_valid_filename
+
+from .utils import to_async
+from .exceptions import PermissionInsufficient
+from .resource_manager import (
+    ResourceManager,
+    ControlCode, AccessCode, Resource,
+    ControlCodeGen, ControlCodeGenAsync, AccessCodeGen, AccessCodeGenAsync,
+)
+
+
+def uuid4_str():
+    """生成一个标准格式的随机UUID字符串"""
+    return str(uuid4())
+
+# 资源与二进制数据转换函数
+DumpsFunction = Callable[[Resource], bytes]
+LoadsFunction = Callable[[bytes], Resource]
+DumpsFunctionAsync = Callable[[Resource], Coroutine[None, None, bytes]]
+LoadsFunctionAsync = Callable[[bytes], Coroutine[None, None, Resource]]
+
+# 文件名生成函数
+FileName = str
+FileNameGen = Callable[[Optional[Resource], Optional[ControlCode]], FileName]
+FileNameGenAsync = Callable[[Optional[Resource], Optional[ControlCode]], Coroutine[None, None, FileName]]
+
+
+class FileBackedResourceManager(
+    Generic[Resource, ControlCode, AccessCode],
+    ResourceManager[FileName, ControlCode, AccessCode]
+):
+    """
+    Subclass of ResourceManager.
+    
+    Store resources in disk files.
+
+    If control/access codes, codes generators and filename generator are all pickle serializable,
+    then the FileBackedResourceManager object can also be.
+    """
+    def __init__(
+        self,
+        data_dir_path: str,
+        dumps_function: Optional[DumpsFunction | DumpsFunctionAsync] = None,
+        loads_function: Optional[LoadsFunction | LoadsFunctionAsync] = None,
+        file_name_gen: Optional[FileNameGen | FileNameGenAsync] = None,
+        *,
+        control_code_gen: Optional[ControlCodeGen | ControlCodeGenAsync] = None,
+        access_code_gen: Optional[AccessCodeGen | AccessCodeGenAsync] = None,
+    ):
+        """
+        初始化一个 FileBackedResourceManager 对象。
+
+        Args:
+            data_dir_path (str): 存储资源文件的目录。
+            dumps_function (Optional[DumpsFunction | DumpsFunctionAsync]): 将资源转换为字节串的函数，
+                默认为 pickle.dumps 。
+            loads_function (Optional[LoadsFunction | LoadsFunctionAsync]): 将字节串解码为资源的函数，
+                默认为 pickle.loads 。
+            file_name_gen (Optional[FileNameGen | FileNameGenAsync]): 根据资源内容（可选）和控制码（可选）生成文件名的函数。
+            control_code_gen (Optional[ControlCodeGen | ControlCodeGenAsync]): 根据资源内容（可选）生成控制码的函数。
+            access_code_gen (Optional[AccessCodeGen | AccessCodeGenAsync]): 根据资源内容（可选）、控制码（可选）、
+                父级访问码（可选）生成访问码的函数。
+        """
+        super().__init__(control_code_gen, access_code_gen)
+
+        # 文件存放路径
+        self.data_dir_path = data_dir_path
+
+        # 数据转换函数
+        if not dumps_function:
+            dumps_function = pickle.dumps
+
+        if not loads_function:
+            loads_function = pickle.loads
+
+        self.dumps_async: DumpsFunctionAsync = to_async(dumps_function)
+        self.loads_async: LoadsFunctionAsync = to_async(loads_function)
+
+        # 文件名生成函数
+        if not file_name_gen:
+            file_name_gen = uuid4_str
+        self._file_name_gen_raw_async: FileNameGenAsync = to_async(file_name_gen)
+
+
+    def _get_path(self, file_name: str) -> str:
+        """
+        获取文件存储的路径。
+        """
+        return os.path.join(self.data_dir_path, file_name)
+
+
+    async def file_name_gen_async(
+        self,
+        resource: Optional[Resource] = None,
+        control_code: Optional[ControlCode] = None
+    ) -> FileName:
+        """
+        包装了生成文件名的函数，使其能够接受接受 resource, control_code 参数。
+        """
+        try:
+            return await self._file_name_gen_raw_async(resource, control_code)
+        except TypeError:
+            try:
+                return await self._file_name_gen_raw_async(resource)
+            except TypeError:
+                return await self._file_name_gen_raw_async()
+
+
+    # ==== 重载父类方法 ====
+
+    @override
+    async def _get_resource_async(self, control_code: ControlCode) -> Resource:
+        """
+        返回资源。
+
+        Args:
+            code (Code): 控制码或访问码。
+
+        Returns:
+            Resource: control_code 对应的资源。
+
+        Raises:
+            FileNotFoundError: 如果文件没有找到。
+            PermissionInsufficient: 如果 control_code 不是控制码。
+        """
+        # 获取文件路径
+        file_name = await super()._get_resource_async(control_code)
+        file_path = self._get_path(file_name)
+
+        # 读取文件
+        async with aiofiles.open(file_path, mode="rb") as file:
+            content = await file.read()
+        return await self.loads_async(content)
+
+
+    @override
+    async def _set_resource_async(self, control_code: ControlCode, resource: Resource) -> None:
+        """
+        记录资源。
+
+        Args:
+            control_code (Code): 控制码。
+
+        Raises:
+            PermissionInsufficient: 如果 file_name_gen 生成了重复的文件名。
+            ValidationError: 如果 file_name_gen 生成了非法的文件名。
+        """
+        # 生成文件名
+        file_name = await self.file_name_gen_async(resource=resource, control_code=control_code)
+        if not is_valid_filename(file_name):
+            raise ValidationError(f"Invalid file name: {file_name}")
+        if file_name in self._control_resource_map.values():
+            raise PermissionInsufficient("Duplicate file name")
+
+        # 写入文件
+        await aiofiles.os.makedirs(self.data_dir_path, exist_ok=True)
+        file_path = self._get_path(file_name)
+        content = await self.dumps_async(resource)
+        async with aiofiles.open(file_path, mode="wb") as file:
+            await file.write(content)
+
+        # 记录
+        await super()._set_resource_async(control_code, file_name)
+
+
+    @override
+    async def _delete_resource_async(self, control_code: ControlCode) -> None:
+        """
+        删除资源。
+
+        Args:
+            control_code (Code): 控制码。
+        """
+        file_name = await super()._get_resource_async(control_code)
+
+        # 删除记录
+        await super()._delete_resource_async(control_code)
+
+        # 删除文件
+        file_path = self._get_path(file_name)
+        if await aiofiles.os.path.isfile(file_path):
+            await aiofiles.os.remove(file_path)

access_control/resource_manager.py

@@ -0,0 +1,540 @@
+"""
+class: ResourceManager
+"""
+
+import asyncio
+from collections.abc import Coroutine, Hashable, Callable
+import functools
+from typing import Dict, Generic, List, Optional, TypeVar, Union
+from uuid import uuid4
+
+from treelib import Tree
+from treelib.exceptions import NodeIDAbsentError
+
+from .utils import to_async, AsyncRLock
+from .exceptions import CodeExistError, PermissionInsufficient, ResourceManagerError
+
+
+# 资源类型
+Resource = TypeVar("Resource")
+
+# 控制码类型，一般是字符串或整数
+ControlCode = TypeVar("ControlCode", bound=Hashable)
+
+# 访问码类型，一般是字符串或整数
+AccessCode = TypeVar("AccessCode", bound=Hashable)
+
+# 控制码和访问码的联合类型
+Code = Union[ControlCode, AccessCode]
+
+# 生成控制码的函数类型
+ControlCodeGen = Callable[[Optional[Resource]], ControlCode]
+
+# 生成访问码的函数类型
+AccessCodeGen = Callable[
+    [Optional[Resource], Optional[ControlCode], Optional[AccessCode]],
+    AccessCode
+]
+
+# 生成控制码的异步函数类型
+ControlCodeGenAsync = Callable[[Optional[Resource]], Coroutine[None, None, ControlCode]]
+
+# 生成访问码的异步函数类型
+AccessCodeGenAsync = Callable[
+    [Optional[Resource], Optional[ControlCode], Optional[AccessCode]],
+    Coroutine[None, None, AccessCode]
+]
+
+
+
+def async_locked(method: Callable) -> Callable:
+    """装饰器：为异步方法自动加上 RLock"""
+    @functools.wraps(method)
+    async def wrapper(self, *args, **kwargs):
+        async with self._lock_async:
+            return await method(self, *args, **kwargs)
+    return wrapper
+
+
+
+class ResourceManager(Generic[Resource, ControlCode, AccessCode]):
+    """
+    Implementing access control for resources.
+
+    Resources can be any Python object.
+
+    A single resource can have multiple access codes, but only one control code.
+
+    If control/access codes, codes generators, and resources are all pickle serializable,
+    then the ResourceManager object can also be.
+    """
+    def __init__(
+        self,
+        control_code_gen: Optional[ControlCodeGen | ControlCodeGenAsync] = None,
+        access_code_gen: Optional[AccessCodeGen | AccessCodeGenAsync] = None,
+    ):
+        """
+        初始化一个 ResourceManager 对象。
+
+        Args:
+            control_code_gen (Optional[ControlCodeGen | ControlCodeGenAsync]): 根据资源内容（可选）生成控制码的函数。
+            access_code_gen (Optional[AccessCodeGen | AccessCodeGenAsync]): 根据资源内容（可选）、控制码（可选）、
+                父级访问码（可选）生成访问码的函数。
+        """
+        # 控制码、访问码生成函数
+        if not control_code_gen:
+            control_code_gen = uuid4
+
+        if not access_code_gen:
+            access_code_gen = control_code_gen
+
+        self._control_code_gen_raw_async: ControlCodeGenAsync = to_async(control_code_gen)
+        self._access_code_gen_raw_async: AccessCodeGenAsync = to_async(access_code_gen)
+
+        # 存储控制码和资源的关系：control_code -> resource
+        self._control_resource_map: Dict[ControlCode, Resource] = {}
+
+        # 存储访问码和控制码的关系：access_code -> control_code
+        self._access_control_map: Dict[AccessCode, ControlCode] = {}
+
+        # 存储资源的访问码树：control_code -> code_tree
+        self._control_code_tree_map: Dict[ControlCode, Tree] = {}
+
+        # 异步锁，用于线程安全
+        self._lock_async = AsyncRLock()
+
+
+    def __len__(self) -> int:
+        """
+        返回资源数量。
+        """
+        return len(self._control_resource_map)
+
+
+    # ==== 子类可能需要重载的方法 ====
+
+
+    async def _get_control_code_async(self, code: Code) -> ControlCode:
+        """
+        返回 code 的控制码。
+
+        Args:
+            code (Code): 控制码或访问码。
+
+        Returns:
+            ControlCode: code 对应的控制码。
+
+        Raises:
+            PermissionInsufficient: 如果 code 不存在。
+        """
+        if await self.is_control_code_async(code):
+            return code
+        if await self.is_access_code_async(code):
+            return self._access_control_map[code]
+        raise PermissionInsufficient("Code not found")
+
+
+    async def _get_tree_async(self, code: Code) -> Tree:
+        """
+        返回 code 的访问控制树。
+
+        Args:
+            code (Code): 控制码或访问码。
+
+        Returns:
+            Tree: code 所在的访问控制树。
+
+        Raises:
+            PermissionInsufficient: 如果 code 不存在。
+            ResourceManagerError: 内部错误：找不到访问树。
+        """
+        control_code = await self._get_control_code_async(code)
+        code_tree = self._control_code_tree_map.get(control_code)
+        if not code_tree:
+            raise ResourceManagerError("Code tree not found")
+        return code_tree
+
+
+    async def _access_async(
+        self,
+        control_code: ControlCode,
+        parent_code: Optional[Code] = None,
+        child_code: Optional[AccessCode] = None
+    ) -> AccessCode:
+        """
+        生成一个访问码。
+
+        Args:
+            control_code (ControlCode): 控制码。
+            parent_code (Optional[Code]): 分享者。
+            child_code (Optional[AccessCode]): 自定义的访问码。若缺省，则由 access_code_gen 生成。
+
+        Raises:
+            CodeExistError: 如果提供的 child_code 已存在，或 access_code_gen 生成了重复的访问码。
+            PermissionInsufficient: 如果不存在 control_code 。
+        """
+        if not await self.is_control_code_async(control_code):
+            raise PermissionInsufficient("Control code not found")
+
+        # 生成访问码
+        access_code = child_code or await self.access_code_gen_async(
+            await self.get_async(control_code),
+            control_code,
+            parent_code
+        )
+        if await self.is_access_code_async(access_code):
+            raise CodeExistError("Access code already exists")
+
+        self._access_control_map[access_code] = control_code
+
+        if not parent_code:
+            parent_code = control_code
+
+        # 将访问码添加到访问码树中
+        code_tree = self._control_code_tree_map[control_code]
+        code_tree.create_node(identifier=access_code, parent=parent_code)
+
+        return access_code
+
+
+    async def _create_tree_async(self, control_code: ControlCode) -> Tree:
+        """
+        创建一棵访问树。
+        """
+        code_tree = Tree()
+        code_tree.create_node(identifier=control_code)
+        self._control_code_tree_map[control_code] = code_tree
+        return code_tree
+
+
+    async def _get_resource_async(self, control_code: ControlCode) -> Resource:
+        """
+        返回资源。
+
+        Args:
+            code (Code): 控制码或访问码。
+
+        Returns:
+            Resource: control_code 对应的资源。
+
+        Raises:
+            PermissionInsufficient: 如果 control_code 不是控制码。
+        """
+        return self._control_resource_map[control_code]
+
+
+    async def _set_resource_async(self, control_code: ControlCode, resource: Resource) -> None:
+        """
+        记录资源。
+
+        Args:
+            control_code (Code): 控制码。
+        """
+        self._control_resource_map[control_code] = resource
+
+
+    async def _delete_resource_async(self, control_code: ControlCode) -> None:
+        """
+        删除资源。
+
+        Args:
+            control_code (Code): 控制码。
+        """
+        self._control_resource_map.pop(control_code, None)
+        self._control_code_tree_map.pop(control_code, None)
+
+
+    # ==== 子类应该不用重载的方法 ====
+
+    @async_locked
+    async def control_code_gen_async(self, resource: Optional[Resource] = None) -> ControlCode:
+        """
+        包装了生成控制码的函数，使其能够接受接受 resource 参数。
+        """
+        try:
+            return await self._control_code_gen_raw_async(resource)
+        except TypeError:
+            return await self._control_code_gen_raw_async()
+
+
+    @async_locked
+    async def access_code_gen_async(
+        self,
+        resource: Optional[Resource] = None,
+        control_code: Optional[ControlCode] = None,
+        parent_access_code: Optional[AccessCode] = None
+    ) -> AccessCode:
+        """
+        包装生成访问码的异步函数，使其能够接受 resource、control_code、parent_access_code 参数。
+        """
+        try:
+            return await self._access_code_gen_raw_async(resource, control_code, parent_access_code)
+        except TypeError:
+            try:
+                return await self._access_code_gen_raw_async(resource, control_code)
+            except TypeError:
+                try:
+                    return await self._access_code_gen_raw_async(resource)
+                except TypeError:
+                    return await self._access_code_gen_raw_async()
+
+
+    @async_locked
+    async def is_control_code_async(self, code: Code) -> bool:
+        """
+        判断一个 code 是否是控制码。
+        """
+        return code in self._control_resource_map
+
+
+    @async_locked
+    async def is_access_code_async(self, code: Code) -> bool:
+        """
+        判断一个 code 是否是访问码。
+        """
+        return code in self._access_control_map
+
+
+    @async_locked
+    async def create_async(
+        self,
+        resource: Resource,
+        control_code: Optional[ControlCode] = None
+    ) -> ControlCode:
+        """
+        创建一个资源。
+
+        Args:
+            resource (Resource): 资源。
+            control_code (Optional[ControlCode]): 自定义的控制码。若缺省，则由 control_code_gen 生成。
+
+        Raises:
+            CodeExistError: 如果提供的 control_code 已存在，或 control_code_gen 生成了重复的控制码。
+        """
+        # 生成控制码
+        control_code = control_code or await self.control_code_gen_async(resource)
+        if await self.is_control_code_async(control_code):
+            raise CodeExistError("Control code already exists")
+
+        # 记录资源
+        await self._set_resource_async(control_code, resource)
+
+        # 初始化 code_tree
+        await self._create_tree_async(control_code)
+
+        return control_code
+
+
+    @async_locked
+    async def replace_async(self, control_code: ControlCode, new_resource: Resource) -> None:
+        """
+        替换一项资源。
+
+        Args:
+            control_code (ControlCode): 被操作的控制码。
+            new_resource (Resource): 新的资源。
+        """
+        if not await self.is_control_code_async(control_code):
+            raise PermissionInsufficient("Control code not found")
+        await self._set_resource_async(control_code, new_resource)
+
+
+    @async_locked
+    async def delete_async(self, control_code: ControlCode) -> None:
+        """
+        删除一项资源及其控制码、所有访问码。
+        """
+        if not await self.is_control_code_async(control_code):
+            raise PermissionInsufficient("Control code not found")
+
+        # 获取该资源对应的访问码树
+        code_tree = self._control_code_tree_map.get(control_code)
+        if code_tree:
+            # 删除所有访问码映射
+            for node in code_tree.all_nodes():
+                if node.identifier != control_code:
+                    self._access_control_map.pop(node.identifier, None)
+
+        # 删除资源映射
+        await self._delete_resource_async(control_code)
+
+
+    @async_locked
+    async def get_async(self, code: Code) -> Resource:
+        """
+        获取一项资源。
+
+        Args:
+            code (Code): 控制码或访问码。
+
+        Raises:
+            PermissionInsufficient: 如果 code 不存在。
+        """
+        control_code = await self._get_control_code_async(code)
+        return await self._get_resource_async(control_code)
+
+
+    @async_locked
+    async def share_async(self, parent_code: Code, child_code: Optional[AccessCode] = None) -> AccessCode:
+        """
+        生成一个新的访问码。
+
+        Args:
+            parent_code (Optional[Code]): 分享者。
+            child_code (Optional[AccessCode]): 自定义的访问码。若缺省，则由 access_code_gen 生成。
+
+        Raises:
+            CodeExistError: 如果提供的 child_code 已存在，或 access_code_gen 生成了重复的访问码 。
+            PermissionInsufficient: 如果不存在 parent_code 。
+        """
+        control_code = await self._get_control_code_async(parent_code)
+        return await self._access_async(
+            control_code=control_code,
+            parent_code=parent_code,
+            child_code=child_code
+        )
+
+
+    @async_locked
+    async def revoke_async(self, ancestor_code: Code, descendant_code: AccessCode) -> None:
+        """
+        撤销一个访问码及其所有子访问码，不能撤销自己。
+
+        Args:
+            ancestor_code (Code): 撤销发起者。
+            descendant_code (Code): 被撤销者。
+
+        Raises:
+            PermissionInsufficient: 
+            - 如果不存在 ancestor_code 或 descendant_code 。
+            - 如果 descendant_code 不是 ancestor_code 的后代。
+
+            ResourceManagerError: 内部错误：找不到访问树。
+        """
+        # 获取访问码树
+        code_tree = await self._get_tree_async(ancestor_code)
+
+        # 检查 ancestor_code 是否是 descendant_code 的祖先节点（TreeLib 的实现已保证自己不是自己的祖先）
+        if (descendant_code not in code_tree) or (not code_tree.is_ancestor(ancestor_code, descendant_code)):
+            raise PermissionInsufficient("Cannot revoke: not ancestor of the descendant code")
+
+        # 获取删除的树节点（descendant_code 及其子树）
+        subtree = code_tree.remove_subtree(descendant_code)
+        subtree_nodes = subtree.all_nodes()
+
+        # 删除访问码映射
+        for node in subtree_nodes:
+            self._access_control_map.pop(node.identifier, None)
+
+
+    @async_locked
+    async def get_access_codes_async(self, code: Code) -> List[AccessCode]:
+        """
+        查看 code 的所有后代。
+
+        Raises:
+            PermissionInsufficient: 如果 code 不存在。
+            ResourceManagerError: 内部错误：找不到访问树。
+        """
+        # 获取访问码树
+        code_tree = await self._get_tree_async(code)
+
+        # 直接获取整个子树，然后排除根节点自身
+        try:
+            subtree = code_tree.subtree(code)
+        except NodeIDAbsentError:
+            # 如果 code 不在树中（可能已被删除），返回空列表
+            return []
+
+        return [
+            node.identifier
+            for node in subtree.all_nodes()
+            if node.identifier != code
+        ]
+
+
+    @async_locked
+    async def transfer_async(
+        self,
+        old_control_code: ControlCode,
+        new_control_code: ControlCode
+    ) -> None:
+        """
+        转让资源所有者。
+
+        原控制码及其访问树被删除，新控制码的资源被修改为原控制码的资源。
+
+        Args:
+            old_control_code (ControlCode): 原控制码。
+            new_control_code (ControlCode): 新控制码。
+        """
+        if not await self.is_control_code_async(old_control_code):
+            raise PermissionInsufficient("Old control code not found")
+        if not await self.is_control_code_async(new_control_code):
+            raise PermissionInsufficient("New control code not found")
+        if old_control_code == new_control_code:
+            return
+
+        # 获取原资源
+        resource = await self.get_async(old_control_code)
+
+        # 将资源转移到新控制码
+        await self.replace_async(new_control_code, resource)
+
+        # 移除原访问码树
+        await self.delete_async(old_control_code)
+
+
+    # ==== 异步方法转同步 ====
+
+    def control_code_gen(self, resource: Optional[Resource] = None) -> ControlCode:
+        """ Synchronous version of `.control_code_gen_async`. """
+        return asyncio.run(self.control_code_gen_async(resource))
+
+    def access_code_gen(
+        self, resource: Optional[Resource] = None,
+        control_code: Optional[ControlCode] = None,
+        parent_access_code: Optional[AccessCode] = None
+    ) -> AccessCode:
+        """ Synchronous version of `.access_code_gen_async`. """
+        return asyncio.run(self.access_code_gen_async(resource, control_code, parent_access_code))
+
+    def is_control_code(self, code: Code) -> bool:
+        """ Synchronous version of `.is_control_code_async`. """
+        return asyncio.run(self.is_control_code_async(code))
+
+    def is_access_code(self, code: Code) -> bool:
+        """ Synchronous version of `.is_access_code_async`. """
+        return asyncio.run(self.is_access_code_async(code))
+
+    def create(self, resource: Resource, control_code: Optional[ControlCode] = None) -> ControlCode:
+        """ Synchronous version of `.create_async`. """
+        return asyncio.run(self.create_async(resource, control_code))
+
+    def replace(self, control_code: ControlCode, new_resource: Resource) -> None:
+        """ Synchronous version of `.replace_async`. """
+        return asyncio.run(self.replace_async(control_code, new_resource))
+
+    def delete(self, control_code: ControlCode) -> None:
+        """ Synchronous version of `.delete_async`. """
+        return asyncio.run(self.delete_async(control_code))
+
+    def get(self, code: Code) -> Resource:
+        """ Synchronous version of `.get_async`. """
+        return asyncio.run(self.get_async(code))
+
+    def share(self, parent_code: Code, child_code: Optional[AccessCode] = None) -> AccessCode:
+        """ Synchronous version of `.share_async`. """
+        return asyncio.run(self.share_async(parent_code, child_code))
+
+    def revoke(self, ancestor_code: Code, descendant_code: AccessCode) -> None:
+        """ Synchronous version of `.revoke_async`. """
+        return asyncio.run(self.revoke_async(ancestor_code, descendant_code))
+
+    def get_access_codes(self, code: Code) -> List[AccessCode]:
+        """ Synchronous version of `.get_access_codes_async`. """
+        return asyncio.run(self.get_access_codes_async(code))
+
+    def transfer(self, old_control_code: ControlCode, new_control_code: ControlCode) -> None:
+        """ Synchronous version of `.transfer_async`. """
+        return asyncio.run(self.transfer_async(old_control_code, new_control_code))

access_control/utils.py

@@ -0,0 +1,97 @@
+"""
+提供了一些与同步、异步函数转换有关的工厂函数。
+
+Pickle 友好。
+"""
+
+import asyncio
+from functools import partial
+from inspect import isawaitable
+from typing import Any, Awaitable, AsyncContextManager, Callable, ContextManager, Optional
+
+# 同步函数类型
+SyncFunction = Callable[..., Any]
+
+# 异步函数类型
+AsyncFunction = Callable[..., Awaitable[Any]]
+
+
+async def _run_func_async(func: Callable, *args, **kwargs):
+    """
+    异步运行一个同步或异步函数。
+    """
+    result = func(*args, **kwargs)
+    if isawaitable(result):
+        return await result
+    return result
+
+def to_async(func: Callable) -> AsyncFunction:
+    """
+    把同步或异步函数转换为异步函数。
+    """
+    return partial(_run_func_async, func)
+
+
+def _run_func_sync(func: Callable, *args, **kwargs):
+    """
+    同步运行一个同步或异步函数。
+    """
+    result = func(*args, **kwargs)
+    if isawaitable(result):
+        return asyncio.run(result)
+    return result
+
+def to_sync(func: Callable) -> SyncFunction:
+    """
+    把同步或异步函数转换为同步函数。
+    """
+    return partial(_run_func_sync, func)
+
+
+def run_within_context(context: ContextManager, func: SyncFunction, *args, **kwargs):
+    """
+    将函数 func 放在上下文里执行。
+    """
+    with context:
+        return func(*args, **kwargs)
+
+
+async def run_within_context_async(context: AsyncContextManager, func: AsyncFunction, *args, **kwargs):
+    """
+    Asynchronous version of `run_within_context`.
+    """
+    async with context:
+        return await func(*args, **kwargs)
+
+
+class AsyncRLock:
+    """简单的异步可重入锁，兼容 Python 3.10"""
+    def __init__(self):
+        self._lock = asyncio.Lock()
+        self._owner: Optional[int] = None   # 持有锁的 task id
+        self._count = 0
+
+    async def acquire(self):
+        current_task = id(asyncio.current_task())
+        if self._owner == current_task:
+            self._count += 1
+            return True
+        await self._lock.acquire()
+        self._owner = current_task
+        self._count = 1
+        return True
+
+    def release(self):
+        if self._owner != id(asyncio.current_task()):
+            raise RuntimeError("Cannot release a lock that is not held by the current task")
+        self._count -= 1
+        if self._count == 0:
+            self._owner = None
+            self._lock.release()
+
+    async def __aenter__(self):
+        await self.acquire()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        self.release()

access_control_async-0.2.5.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: access-control-async
+Version: 0.2.5
+Summary: A brief description of your access control library
+Author-email: Jerry <wujr24@m.fudan.edu.cn>
+License: MIT
+Project-URL: Homepage, https://github.com/Jerry-Wu-GitHub/access-control
+Project-URL: Repository, https://github.com/Jerry-Wu-GitHub/access-control.git
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: treelib
+Requires-Dist: aiofiles
+Requires-Dist: pathvalidate
+Dynamic: license-file
+
+# Access Control
+
+一个轻量级的 Python 资源访问控制库，支持基于控制码（Control Code）和访问码（Access Code）的细粒度权限管理，并提供可选的磁盘持久化能力。
+
+## 特性
+
+- **两级授权模型**：每个资源拥有唯一的控制码（所有者权限）和多个访问码（分享权限）
+- **树形访问结构**：访问码可继续衍生子访问码，形成层级分享关系
+- **同步与异步双接口**：所有方法均提供 `*_async` 异步版本和同步版本
+- **可插拔的码生成器**：支持自定义控制码/访问码生成逻辑
+- **磁盘持久化**：`FileBackedResourceManager` 可将资源序列化保存到文件系统
+- **Pickle 友好**：管理器对象可序列化（需保证内部对象可 Pickle）
+
+## 安装
+
+```bash
+pip install access-control-async
+```
+
+或者直接从源码安装：
+
+```bash
+git clone https://github.com/Jerry-Wu-GitHub/access-control.git
+cd access-control
+pip install .
+```
+
+## 快速开始
+
+### 基本用法（内存存储）
+
+```python
+from access_control import ResourceManager
+
+# 创建管理器（控制码和访问码默认使用 uuid4）
+manager = ResourceManager()
+
+# 创建一个资源
+resource = {"data": "secret message"}
+control_code = manager.create(resource)  # 返回控制码，如 "3a6f2b1c..."
+
+# 基于控制码分享访问码
+access_code1 = manager.share(control_code)
+access_code2 = manager.share(control_code)
+
+# 从访问码获取资源
+retrieved = manager.get(access_code1)
+assert retrieved == resource
+
+# 查看某个码的所有后代访问码
+codes = manager.get_access_codes(control_code)   # [access_code1, access_code2]
+
+# 撤销一个访问码及其所有子访问码
+manager.revoke(control_code, access_code1)
+
+# 删除整个资源（包括所有访问码）
+manager.delete(control_code)
+```
+
+### 异步接口
+
+所有操作都提供 `*_async` 异步版本，便于集成到异步应用中：
+
+```python
+import asyncio
+from access_control import ResourceManager
+
+async def main():
+    manager = ResourceManager()
+    control_code = await manager.create_async({"data": "async test"})
+    access_code = await manager.share_async(control_code)
+    resource = await manager.get_async(access_code)
+    print(resource)
+
+asyncio.run(main())
+```
+
+### 使用文件持久化
+
+```python
+import asyncio
+from access_control import FileBackedResourceManager
+
+async def main():
+    # 资源将保存在 ./data 目录下
+    manager = FileBackedResourceManager("./data")
+
+    # 创建资源（自动序列化到磁盘）
+    resource = {"user": "alice", "score": 100}
+    control_code = await manager.create_async(resource)
+
+    # 即使重启程序，只要 data 目录存在，即可恢复
+    new_manager = FileBackedResourceManager("./data")
+    same_resource = await new_manager.get_async(control_code)
+    print(same_resource)
+
+asyncio.run(main())
+```
+
+### 自定义码生成器
+
+你可以传入自己的生成函数（同步或异步均可）：
+
+```python
+import hashlib
+from access_control import ResourceManager
+
+def my_control_code_gen(resource):
+    # 根据资源内容生成控制码
+    return hashlib.md5(str(resource).encode()).hexdigest()[:8]
+
+def my_access_code_gen(resource, control_code, parent_code):
+    # 自定义访问码生成逻辑
+    return f"share_{control_code}_{parent_code}"
+
+manager = ResourceManager(
+    control_code_gen=my_control_code_gen,
+    access_code_gen=my_access_code_gen
+)
+
+control = manager.create({"foo": "bar"})
+print(control)  # 输出类似 "d3b07384"
+```
+
+## API 概览
+
+### `ResourceManager[Resource, ControlCode, AccessCode]`
+
+主要方法（均提供同步版本和 `*_async` 异步版本）：
+
+| 方法 | 描述 |
+|------|------|
+| `create(resource, control_code=None)` | 创建资源，返回控制码 |
+| `get(code)` | 通过控制码或访问码获取资源 |
+| `share(parent_code, child_code=None)` | 生成新的访问码 |
+| `revoke(ancestor_code, descendant_code)` | 撤销一个访问码及其所有子访问码 |
+| `get_access_codes(code)` | 返回某个码的所有后代访问码 |
+| `replace(control_code, new_resource)` | 替换控制码对应的资源 |
+| `transfer(old_control, new_control)` | 将资源所有权转移给另一个控制码 |
+| `delete(control_code)` | 删除资源及其所有关联码 |
+| `is_control_code(code)` / `is_access_code(code)` | 判断码的类型 |
+
+### `FileBackedResourceManager`
+
+继承自 `ResourceManager`，额外接受以下构造参数：
+
+- `data_dir_path`: 存储文件的目录路径
+- `dumps_function` / `loads_function`: 自定义序列化函数（默认 `pickle.dumps` / `pickle.loads`）
+- `file_name_gen`: 根据资源和控制码生成文件名的函数（默认使用 `uuid4`）
+
+所有资源的存取均自动读写磁盘文件。
+
+## 依赖
+
+- Python >= 3.10
+- `treelib` – 用于维护访问码树结构
+- `aiofiles` – 异步文件操作
+- `pathvalidate` – 校验文件名的合法性
+
+## 许可证
+
+本项目使用 [MIT 许可证](LICENSE)。

access_control_async-0.2.5.dist-info/RECORD

@@ -0,0 +1,10 @@
+access_control/__init__.py,sha256=ignBnuu2uQQiQIJnIcLTPHLpbfVoQ6abXcN1XgIZKzI,234
+access_control/exceptions.py,sha256=frKL4gKgisnGwnlZlqKUJeBFCQvtLdPN428Obr4HkkM,380
+access_control/file_backed_resource_manager.py,sha256=0Mb16KL5_qlnA4gFG-j7RhONuNDS3c-s9NmcHb2Q2UQ,7012
+access_control/resource_manager.py,sha256=nDr5g5pHRqnNbMAhKvbIXInizZe2B3gHAjrrHq7RzIg,19151
+access_control/utils.py,sha256=aL8lDKE4ynVIZ6wVV1B2vE28UN0aK2rgZiBux381Fms,2684
+access_control_async-0.2.5.dist-info/licenses/LICENSE,sha256=errzu9jbnGCiEZ50jZxag9tkLf5opFvlVTDC8yfYlQA,1081
+access_control_async-0.2.5.dist-info/METADATA,sha256=d3LcuRFrl366JuWhK626RpbVV12z7nEkUk_L1hKQNQc,5841
+access_control_async-0.2.5.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+access_control_async-0.2.5.dist-info/top_level.txt,sha256=Ydmx4mMJO0arjcPAL3zqz9yMQjF69QogVQtoQJEeOok,15
+access_control_async-0.2.5.dist-info/RECORD,,

access_control_async-0.2.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

access_control_async-0.2.5.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

access_control_async-0.2.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+access_control