access-control-async 0.2.5__tar.gz

access_control_async-0.2.5/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,162 @@
+# 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/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "access-control-async"    # 你的包名
+version = "0.2.5"                # 当前版本
+description = "A brief description of your access control library"  # 简短描述
+readme = "README.md"             # 自述文件，PyPI 会将其渲染为项目首页
+authors = [{name = "Jerry", email = "wujr24@m.fudan.edu.cn"}]  # 替换为你的信息
+license = {text = "MIT"}         # 指定许可证，与你的 LICENSE 文件一致
+classifiers = [                  # 帮助用户在 PyPI 上找到你的项目
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.10"
+dependencies = [                 # 项目的运行时依赖，从 requirements.txt 移植
+    "treelib",
+    "aiofiles",
+    "pathvalidate",
+]
+
+[project.urls]                   # 可选，但推荐，指向你的项目主页或仓库
+Homepage = "https://github.com/Jerry-Wu-GitHub/access-control"
+Repository = "https://github.com/Jerry-Wu-GitHub/access-control.git"
+
+[tool.setuptools.packages.find]
+where = ["src"]                         # 在 src 目录下找包

access_control_async-0.2.5/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

access_control_async-0.2.5/src/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_async-0.2.5/src/access_control/exceptions.py

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

access_control_async-0.2.5/src/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)