完善开发文档与更新函数注释

2025-01-27 11:16:26 +08:00
parent de4f2c6d52
commit 0db36a6218
17 changed files with 932 additions and 254 deletions
@@ -1,2 +1,61 @@
-程序缓存模块
-=====================
+:mod:`cache` -- 应用缓存模块
+================================
+
+:mod:`cache` 模块源代码在文件夹 `applications/common/utils/cache.py` 下，主要用于简单的程序数据缓存。
+
+目前此模块仅启用应用程序缓存，暂时没有联动 Redis 等数据库缓存的功能，后续有意向添加。您可以在自己的项目中添加相关的函数，当然也非常欢迎提交 PR ，一起完善项目。
+
+.. warning::
+
+    此模块目前仅用于简单的缓存记录，不能记录大量的、持久的缓存。缓存内容存在内存中，在程序结束后清空！具体的例子是 `系统监控` 页面，用于缓存 5 秒内的 CPU 与内存
+    的监控数据。
+
+.. module:: cache
+
+变量
+-----------
+
+.. py:data:: cache_dict
+
+    一个字典，用于存放缓存数据与缓存的过期时间戳。
+
+函数
+-----------
+
+.. function:: cache_set_internal(key, value, expired=5)
+
+    程序内部实现的记录缓存，用于简单、体量不大的缓存记录，在程序结束后销毁。对于高速、体量大的环境请配置 Redis 等服务自行记录。
+    记录缓存，存储键值对，并记录当前时间作为缓存的时间戳。
+
+    :param key: 键
+    :param value: 值
+    :param expired: 过期时间（秒），默认5秒
+
+.. function:: cache_get_internal(key)
+
+    获取缓存，根据键从缓存中获取值，并检查是否过期。
+
+    :param key: 键
+    :return: 如果缓存存在且未过期，返回缓存的值；否则返回 None
+
+.. function:: cache_auto_internal(key, call, expired=5)
+
+    如果缓存存在直接返回缓存内容，缓存不存在或者过期执行 call 函数，并取得返回值记录并返回。
+
+    :param key: 键
+    :param call: 获取新值的地方
+    :param expired: 过期时间（秒），默认5秒
+
+    **示例：**
+
+    .. code-block:: python
+
+        from application.common.utils.cache import cache_auto_internal
+
+        def fetch_data():
+            # 模拟从数据库或接口获取数据
+            return "new_data"
+
+        # 使用 cache_auto_internal 获取缓存或调用 fetch_data 获取新值
+        result = cache_auto_internal("my_key", fetch_data, expired=10)
+        print(result)  # 输出: "new_data"（如果缓存不存在或已过期）
@@ -0,0 +1,114 @@
+:mod:`captcha` -- 验证码生成模块
+==================================
+
+:mod:`captcha` 模块源代码在文件夹 `applications/common/utils/captcha.py` 下，主要用于生成验证码图片。
+
+.. module:: captcha
+
+类
+------
+
+.. class:: vieCode
+
+    生成验证码图片。
+
+    .. py:attribute:: __fontSize
+        :type: int
+
+        字体大小，默认为 20。
+
+    .. py:attribute:: __width
+        :type: int
+
+        画布宽度，默认为 120。
+
+    .. py:attribute:: __heigth
+        :type: int
+
+        画布高度，默认为 45。
+
+    .. py:attribute:: __length
+        :type: int
+
+        验证码长度，默认为 4。
+
+    .. py:attribute:: __draw
+        :type: ImageDraw.Draw
+
+        画布对象。
+
+    .. py:attribute:: __img
+        :type: Image.Image
+
+        图片对象。
+
+    .. py:attribute:: __code
+        :type: list
+
+        验证码字符。
+
+    .. py:attribute:: __str
+        :type: str
+
+        自定义验证码字符集。
+
+    .. py:attribute:: __inCurve
+        :type: bool
+
+        是否绘制干扰曲线，默认为 True。
+
+    .. py:attribute:: __inNoise
+        :type: bool
+
+        是否绘制干扰点，默认为 True。
+
+    .. py:attribute:: __type
+        :type: int
+
+        验证码类型：1-纯字母，2-数字字母混合，默认为 2。
+
+    .. py:attribute:: __fontPatn
+        :type: str
+
+        字体路径，默认为 ``applications/common/utils/fonts/captcha.ttf``。
+
+    .. method:: GetCodeImage(size=80, length=4)
+
+        生成验证码图片及其对应的验证码字符。
+
+        :param size: 验证码字体大小，默认为 80。
+        :param length: 验证码字符长度，默认为 4。
+        :return: 返回验证码图片对象和验证码字符。
+
+        **示例：**
+
+        .. code-block:: python
+
+            vc = vieCode()
+            img, code = vc.GetCodeImage(size=60, length=6)
+            img.show()  # 显示验证码图片
+            print("验证码:", code)  # 输出验证码字符
+
+    .. method:: __cerateFilter()
+
+        对验证码图片进行模糊处理，增加识别难度。
+
+    .. method:: __createCode()
+
+        生成验证码字符。
+
+    .. method:: __createImage()
+
+        创建画布并设置背景颜色。
+
+    .. method:: __createNoise()
+
+        在验证码图片上绘制干扰点。
+
+    .. method:: __createCurve()
+
+        在验证码图片上绘制干扰曲线。
+
+    .. method:: __printString()
+
+        在画布上打印验证码字符。
@@ -0,0 +1,39 @@
+:mod:`http` -- JSON 响应正文生成模块
+=======================================
+
+:mod:`http` 模块源代码在文件夹 `applications/common/utils/http.py` 下，主要用于生成 JSON 格式的响应正文。
+
+对于大部分 JSON 格式响应的数据，请尽量遵循响应格式规范。如此方便后续前后端的分离和项目的构建。
+
+.. module:: http
+
+函数
+------------
+
+.. function:: success_api(msg: str = "成功")
+
+    返回成功的 API 响应。
+
+    :param msg: 成功消息内容，默认为 "成功"。
+    :return: 返回 JSON 格式的响应，包含 `success` 和 `msg` 字段。
+
+
+.. function:: fail_api(msg: str = "失败")
+
+    返回失败的 API 响应。
+
+    :param msg: 失败消息内容，默认为 "失败"。
+    :return: 返回 JSON 格式的响应，包含 `success` 和 `msg` 字段。
+
+
+.. function:: table_api(msg: str = "", count=0, data=None, limit=10)
+
+    返回动态表格渲染所需的 API 响应。
+
+    :param msg: 响应消息内容，默认为空字符串。
+    :param count: 数据总数，默认为 0。
+    :param data: 表格数据，默认为 None。
+    :param limit: 每页数据条数，默认为 10。
+    :return: 返回 JSON 格式的响应，包含 `msg`、`code`、`data`、`count` 和 `limit` 字段。
+
+
@@ -1,3 +1,5 @@
+.. module:: applications.common.utils
+
 .. title:: 辅助函数

 目录索引
@@ -6,3 +8,9 @@
    :maxdepth: 1

    cache
+    captcha
+    http
+    mail
+    rights
+    upload
+    validate
@@ -0,0 +1,60 @@
+:mod:`mail` -- 邮件模块
+==================================
+
+:mod:`mail` 模块源代码在文件夹 `applications/common/utils/mail.py` 下，主要用于邮件的发送。
+
+.. module:: mail
+
+函数
+---------------
+
+.. function:: get_all(receiver=None, subject=None, content=None)
+
+   获取邮件列表，支持根据接收者、主题和内容进行筛选。
+
+   返回的列表中的字典结构如下::
+
+       {
+           "content": "",  # HTML 内容
+           "create_at": "2022-12-25T10:51:17",  # 创建时间
+           "id": 17,  # 邮件ID
+           "realname": "超级管理",  # 创建者姓名
+           "receiver": "",  # 接收者
+           "subject": ""  # 邮件主题
+       }
+
+   :param receiver: 接收者邮箱地址，支持模糊查询。
+   :param subject: 邮件主题，支持模糊查询。
+   :param content: 邮件内容，支持模糊查询。
+   :return: 返回符合条件的邮件列表。
+
+
+.. function:: add(receiver, subject, content, user_id)
+
+   发送一封邮件，并将发送记录保存到数据库。 **该方法被邮件发送的视图函数调用。**
+
+   :param receiver: 接收者邮箱地址，多个邮箱用英文分号隔开。
+   :param subject: 邮件主题。
+   :param content: 邮件内容（HTML 格式）。
+   :param user_id: 发送者用户ID，表示谁发送了这封邮件。
+                  可以使用 `from flask_login import current_user; current_user.id` 获取当前登录用户的ID。
+   :return: 发送成功返回 True，失败报错。
+
+
+.. function:: delete(id)
+
+   删除指定的邮件记录。
+
+   :param id: 邮件ID。
+   :return: 删除成功返回 True，失败返回 False。
+
+
+.. function:: send_mail(subject, recipients, content)
+
+   发送邮件（不记录发送日志）。
+
+   注意：如果发送失败会抛出异常，请使用 try-except 进行捕获。
+
+   :param subject: 邮件主题。
+   :param recipients: 接收者邮箱地址，多个邮箱用英文分号隔开。
+   :param content: 邮件内容（HTML 格式）。
@@ -0,0 +1,61 @@
+:mod:`rights` -- 权限验证模块
+==================================
+
+:mod:`rights` 模块源代码在文件夹 `applications/common/utils/rights.py` 下，主要用于权限验证。
+
+.. module:: rights
+
+函数
+---------------
+
+.. function:: authorize(power: str, log: bool = False)
+
+    用户权限判断，用于判断目前会话用户是否拥有访问权限。此函数是一个修饰器，可用于修饰视图函数。
+    在模板中有与之对应的全局非修饰函数 authorize ，此函数定义位于 `applications/extensions/init_template_directives.py` 。
+    示例中将会展示两种方式的用法。
+
+    :param power: 权限标识
+    :type power: str
+    :param log: 是否记录日志，默认为 False
+    :type log: bool, optional
+
+    **修饰函数示例：**
+
+    .. code-block:: python
+
+        @app.route("/test")
+        @authorize("system:power:remove", log=True)
+        def test_index():
+            return 'You are allowed.'
+
+
+    **在前端模板中：**
+
+    .. code-block:: html
+
+        {% if authorize("system:user:edit") %}
+            <button class="pear-btn pear-btn-primary pear-btn-sm" lay-event="edit">
+            <i class="pear-icon pear-icon-edit"></i>
+            </button>
+        {% endif %}
+
+
+    .. important::
+
+        `if authorize("system:user:edit")` 的方式仅适用于 **前端模板渲染** ，不得用于后端代码判断。
+        如果后端想要使用，请使用 **power in session.get('permissions')** 来判断， `power` 是 `权限标识` 。
+
+        .. code-block:: python
+
+            from flask import session
+
+            ...
+
+            @bp.get('/test')
+            def test():
+                if 'system:user:edit' in session.get('permissions'):
+                    ...
+
+                ...
+
+
@@ -0,0 +1,34 @@
+:mod:`upload` -- 文件上传模块
+==================================
+
+:mod:`upload` 模块源代码在文件夹 `applications/common/utils/upload.py` 下，主要用于文件上传，目前主要用于图片上传。
+
+.. module:: upload
+
+函数
+---------------
+
+.. function:: get_photo(page, limit)
+
+   分页获取图片列表，并按创建时间降序排列。
+
+   :param page: 当前页码。
+   :param limit: 每页显示的图片数量。
+   :return: 返回图片列表和图片总数。
+
+
+.. function:: upload_one(photo, mime)
+
+   上传一张图片，并保存图片信息到数据库。
+
+   :param photo: 图片文件对象。
+   :param mime: 图片的 MIME 类型。
+   :return: 返回图片的访问 URL。
+
+
+.. function:: delete_photo_by_id(_id)
+
+   根据图片 ID 删除图片及其记录。
+
+   :param _id: 图片 ID。
+   :return: 返回删除操作的结果（数据库中删除的个数，成功非0）。
@@ -0,0 +1,231 @@
+:mod:`validate` -- 效验模块
+==================================
+
+:mod:`validate` 模块源代码在文件夹 `applications/common/utils/rights.py` 下，主要用于数据效验与过滤。
+
+.. module:: validate
+
+函数
+-------------
+
+.. function:: str_escape(s)
+
+   对字符串进行 XSS 过滤，返回转义后的安全字符串。
+
+   :param s: 需要转义的字符串。
+   :return: 返回转义后的字符串，如果输入为空则返回 None。
+
+
+.. function:: between(*args, **kwargs)
+
+   验证数字是否介于最小值和最大值之间。
+   适用于整数、浮点数、小数和日期等类型。
+
+   :param value: 需要验证的数字。
+   :param min: 数字的最小值（可选）。
+   :param max: 数字的最大值（可选）。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import between
+
+      between(5, min=2)  # True
+      between(13.2, min=13, max=14)  # True
+      between(500, max=400)  # ValidationFailure(func=between, args=...)
+
+
+.. function:: domain(*args, **kwargs)
+
+   验证给定值是否为有效的域名。
+
+   :param value: 需要验证的域名字符串。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import domain
+
+      domain('example.com')  # True
+      domain('example.com/')  # ValidationFailure(func=domain, ...)
+
+
+.. function:: email(*args, **kwargs)
+
+   验证给定值是否为有效的电子邮件地址。
+
+   :param value: 需要验证的电子邮件地址。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import email
+
+      email('someone@example.com')  # True
+      email('bogus@@')  # ValidationFailure(func=email, ...)
+
+
+.. function:: iban(*args, **kwargs)
+
+   验证给定值是否为有效的 IBAN 代码。
+
+   :param value: 需要验证的 IBAN 代码。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import iban
+
+      iban('DE29100500001061045672')  # True
+      iban('123456')  # ValidationFailure(func=iban, ...)
+
+
+.. function:: ipv4(*args, **kwargs)
+
+   验证给定值是否为有效的 IPv4 地址。
+
+   :param value: 需要验证的 IPv4 地址。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import ipv4
+
+      ipv4('123.0.0.7')  # True
+      ipv4('900.80.70.11')  # ValidationFailure(func=ipv4, args={'value': '900.80.70.11'})
+
+
+.. function:: ipv6(*args, **kwargs)
+
+   验证给定值是否为有效的 IPv6 地址。
+
+   :param value: 需要验证的 IPv6 地址。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import ipv6
+
+      ipv6('abcd:ef::42:1')  # True
+      ipv6('abc.0.0.1')  # ValidationFailure(func=ipv6, args={'value': 'abc.0.0.1'})
+
+
+.. function:: length(*args, **kwargs)
+
+   验证给定字符串的长度是否在指定范围内。
+
+   :param value: 需要验证的字符串。
+   :param min: 字符串的最小长度（可选）。
+   :param max: 字符串的最大长度（可选）。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import length
+
+      length('something', min=2)  # True
+      length('something', min=9, max=9)  # True
+      length('something', max=5)  # ValidationFailure(func=length, ...)
+
+
+.. function:: mac_address(*args, **kwargs)
+
+   验证给定值是否为有效的 MAC 地址。
+
+   :param value: 需要验证的 MAC 地址。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import mac_address
+
+      mac_address('01:23:45:67:ab:CD')  # True
+      mac_address('00:00:00:00:00')  # ValidationFailure(func=mac_address, args={'value': '00:00:00:00:00'})
+
+
+.. function:: slug(*args, **kwargs)
+
+   验证给定值是否为有效的 Slug 格式。
+   有效的 Slug 只能包含字母数字字符、连字符和下划线。
+
+   :param value: 需要验证的字符串。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import slug
+
+      slug('my.slug')  # ValidationFailure(func=slug, args={'value': 'my.slug'})
+      slug('my-slug-2134')  # True
+
+
+.. function:: url(*args, **kwargs)
+
+   验证给定值是否为有效的 URL。
+
+   :param value: 需要验证的 URL。
+   :param public: 是否仅允许公共 URL（可选）。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import url
+
+      url('http://foobar.dk')  # True
+      url('http://10.0.0.1')  # True
+      url('http://foobar.d')  # ValidationFailure(func=url, ...)
+      url('http://10.0.0.1', public=True)  # ValidationFailure(func=url, ...)
+
+
+.. function:: uuid(*args, **kwargs)
+
+   验证给定值是否为有效的 UUID。
+
+   :param value: 需要验证的 UUID。
+   :return: 如果验证成功返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import uuid
+
+      uuid('2bc1c94f-0deb-43e9-92a1-4775189ec9f8')  # True
+      uuid('2bc1c94f 0deb-43e9-92a1-4775189ec9f8')  # ValidationFailure(func=uuid, ...)
+
+
+.. function:: even(value)
+
+   验证给定值是否为偶数。
+
+   :param value: 需要验证的数字。
+   :return: 如果是偶数返回 True，否则返回 ValidationFailure。
+
+   **示例：**
+
+   .. code-block:: python
+
+      from applications.common.utils.validate import even
+
+      even(4)  # True
+      even(5)  # ValidationFailure(func=even, args={'value': 5})