aio-scrapy 2.1.4__py3-none-any.whl → 2.1.6__py3-none-any.whl

aioscrapy/utils/curl.py

@@ -1,3 +1,14 @@
+"""
+cURL command parsing utilities for aioscrapy.
+aioscrapy的cURL命令解析实用工具。
+
+This module provides utilities for converting cURL commands to aioscrapy Request objects.
+It parses cURL command syntax and extracts relevant parameters like headers, cookies,
+authentication, and request body.
+此模块提供了将cURL命令转换为aioscrapy Request对象的实用工具。
+它解析cURL命令语法并提取相关参数，如标头、cookie、身份验证和请求正文。
+"""
+
 import argparse
 import warnings
 from shlex import split
@@ -8,69 +19,189 @@ from w3lib.http import basic_auth_header
 
 
 class CurlParser(argparse.ArgumentParser):
+    """
+    Custom ArgumentParser for parsing cURL commands.
+    用于解析cURL命令的自定义ArgumentParser。
+
+    This class extends the standard ArgumentParser to provide better error handling
+    for cURL command parsing. Instead of printing to stderr and exiting, it raises
+    a ValueError with a descriptive message when parsing fails.
+    此类扩展了标准ArgumentParser，为cURL命令解析提供更好的错误处理。
+    当解析失败时，它会引发带有描述性消息的ValueError，而不是打印到stderr并退出。
+    """
+
     def error(self, message):
+        """
+        Override the default error method to raise ValueError instead of exiting.
+        覆盖默认的error方法，引发ValueError而不是退出。
+
+        Args:
+            message: The error message from the ArgumentParser.
+                    来自ArgumentParser的错误消息。
+
+        Raises:
+            ValueError: Always raised with a descriptive error message.
+                       始终引发带有描述性错误消息的ValueError。
+        """
         error_msg = f'There was an error parsing the curl command: {message}'
         raise ValueError(error_msg)
 
 
+# Create a parser instance for cURL commands
+# 创建用于cURL命令的解析器实例
 curl_parser = CurlParser()
-curl_parser.add_argument('url')
-curl_parser.add_argument('-H', '--header', dest='headers', action='append')
-curl_parser.add_argument('-X', '--request', dest='method')
-curl_parser.add_argument('-d', '--data', '--data-raw', dest='data')
-curl_parser.add_argument('-u', '--user', dest='auth')
+
+# Add arguments for the main cURL options we want to support
+# 添加我们想要支持的主要cURL选项的参数
+curl_parser.add_argument('url')  # The target URL (positional argument)
+curl_parser.add_argument('-H', '--header', dest='headers', action='append')  # HTTP headers
+curl_parser.add_argument('-X', '--request', dest='method')  # HTTP method (GET, POST, etc.)
+curl_parser.add_argument('-d', '--data', '--data-raw', dest='data')  # Request body data
+curl_parser.add_argument('-u', '--user', dest='auth')  # Basic authentication credentials
 
 
+# List of cURL arguments that can be safely ignored
+# These arguments don't affect the Request object we're building
+# cURL参数列表，可以安全地忽略
+# 这些参数不会影响我们正在构建的Request对象
 safe_to_ignore_arguments = [
     ['--compressed'],
     # `--compressed` argument is not safe to ignore, but it's included here
     # because the `HttpCompressionMiddleware` is enabled by default
-    ['-s', '--silent'],
-    ['-v', '--verbose'],
-    ['-#', '--progress-bar']
+    # `--compressed`参数实际上不安全忽略，但它包含在这里
+    # 因为`HttpCompressionMiddleware`默认启用
+    ['-s', '--silent'],  # Don't show progress meter or error messages
+    ['-v', '--verbose'],  # Make the operation more talkative
+    ['-#', '--progress-bar']  # Display transfer progress as a progress bar
 ]
 
+# Add all the safe-to-ignore arguments to the parser
+# 将所有可以安全忽略的参数添加到解析器
 for argument in safe_to_ignore_arguments:
     curl_parser.add_argument(*argument, action='store_true')
 
 
 def _parse_headers_and_cookies(parsed_args):
+    """
+    Extract headers and cookies from parsed cURL arguments.
+    从解析的cURL参数中提取标头和cookie。
+
+    This internal helper function processes the headers from cURL arguments,
+    separating regular headers from cookies. It also handles basic authentication
+    by converting it to an Authorization header.
+    此内部辅助函数处理来自cURL参数的标头，将常规标头与cookie分开。
+    它还通过将基本身份验证转换为Authorization标头来处理基本身份验证。
+
+    Args:
+        parsed_args: The parsed arguments from the cURL command.
+                    来自cURL命令的解析参数。
+
+    Returns:
+        tuple: A tuple containing:
+              包含以下内容的元组：
+              - headers (list): List of (name, value) tuples for HTTP headers.
+                              HTTP标头的(名称, 值)元组列表。
+              - cookies (dict): Dictionary of cookie names and values.
+                              cookie名称和值的字典。
+    """
     headers = []
     cookies = {}
+
+    # Process each header from the cURL command
+    # 处理来自cURL命令的每个标头
     for header in parsed_args.headers or ():
+        # Split the header into name and value
+        # 将标头分成名称和值
         name, val = header.split(':', 1)
         name = name.strip()
         val = val.strip()
+
+        # Special handling for Cookie headers
+        # 对Cookie标头的特殊处理
         if name.title() == 'Cookie':
+            # Parse the cookie string and add each cookie to the cookies dict
+            # 解析cookie字符串并将每个cookie添加到cookies字典
             for name, morsel in SimpleCookie(val).items():
                 cookies[name] = morsel.value
         else:
+            # Add regular headers to the headers list
+            # 将常规标头添加到标头列表
             headers.append((name, val))
 
+    # Handle basic authentication if provided
+    # 如果提供了基本身份验证，则处理它
     if parsed_args.auth:
+        # Split the auth string into username and password
+        # 将auth字符串分成用户名和密码
         user, password = parsed_args.auth.split(':', 1)
+        # Create and add the Authorization header
+        # 创建并添加Authorization标头
         headers.append(('Authorization', basic_auth_header(user, password)))
 
     return headers, cookies
 
 
 def curl_to_request_kwargs(curl_command, ignore_unknown_options=True):
-    """Convert a cURL command syntax to Request kwargs.
-
-    :param str curl_command: string containing the curl command
-    :param bool ignore_unknown_options: If true, only a warning is emitted when
-                                        cURL options are unknown. Otherwise
-                                        raises an error. (default: True)
-    :return: dictionary of Request kwargs
     """
+    Convert a cURL command to Request keyword arguments.
+    将cURL命令转换为Request关键字参数。
+
+    This function parses a cURL command string and converts it to a dictionary
+    of keyword arguments that can be used to create an aioscrapy Request object.
+    It handles common cURL options like headers, cookies, method, data, and
+    authentication.
+    此函数解析cURL命令字符串，并将其转换为可用于创建aioscrapy Request对象的
+    关键字参数字典。它处理常见的cURL选项，如标头、cookie、方法、数据和身份验证。
+
+    Args:
+        curl_command: String containing the complete curl command.
+                     包含完整curl命令的字符串。
+        ignore_unknown_options: If True, only a warning is emitted when cURL options
+                               are unknown. Otherwise raises an error.
+                               如果为True，则在cURL选项未知时只发出警告。
+                               否则引发错误。
+                               Defaults to True.
+                               默认为True。
 
+    Returns:
+        dict: Dictionary of Request keyword arguments, which may include:
+              Request关键字参数的字典，可能包括：
+              - method: HTTP method (GET, POST, etc.)
+                       HTTP方法（GET、POST等）
+              - url: The target URL
+                    目标URL
+              - headers: List of (name, value) header tuples
+                        (名称, 值)标头元组的列表
+              - cookies: Dictionary of cookie names and values
+                        cookie名称和值的字典
+              - body: Request body data
+                     请求正文数据
+
+    Raises:
+        ValueError: If the command doesn't start with 'curl', or if unknown options
+                   are encountered and ignore_unknown_options is False.
+                   如果命令不以'curl'开头，或者如果遇到未知选项且
+                   ignore_unknown_options为False。
+
+    Example:
+        >>> kwargs = curl_to_request_kwargs('curl -X POST "http://example.com" -H "Content-Type: application/json" -d \'{"key": "value"}\'')
+        >>> request = Request(**kwargs)
+    """
+    # Split the command string into arguments
+    # 将命令字符串分割成参数
     curl_args = split(curl_command)
 
+    # Verify that the command starts with 'curl'
+    # 验证命令以'curl'开头
     if curl_args[0] != 'curl':
         raise ValueError('A curl command must start with "curl"')
 
+    # Parse the arguments, separating known from unknown
+    # 解析参数，将已知参数与未知参数分开
     parsed_args, argv = curl_parser.parse_known_args(curl_args[1:])
 
+    # Handle unknown arguments
+    # 处理未知参数
     if argv:
         msg = f'Unrecognized options: {", ".join(argv)}'
         if ignore_unknown_options:
@@ -78,26 +209,47 @@ def curl_to_request_kwargs(curl_command, ignore_unknown_options=True):
         else:
             raise ValueError(msg)
 
+    # Get the URL from the parsed arguments
+    # 从解析的参数中获取URL
     url = parsed_args.url
 
     # curl automatically prepends 'http' if the scheme is missing, but Request
-    # needs the scheme to work
+    # needs the scheme to work, so we add it if necessary
+    # curl在方案缺失时自动添加'http'，但Request需要方案才能工作，
+    # 因此我们在必要时添加它
     parsed_url = urlparse(url)
     if not parsed_url.scheme:
         url = 'http://' + url
 
+    # Get the HTTP method or default to GET
+    # 获取HTTP方法或默认为GET
     method = parsed_args.method or 'GET'
 
+    # Start building the result dictionary
+    # 开始构建结果字典
     result = {'method': method.upper(), 'url': url}
 
+    # Extract headers and cookies from the parsed arguments
+    # 从解析的参数中提取标头和cookie
     headers, cookies = _parse_headers_and_cookies(parsed_args)
 
+    # Add headers to the result if present
+    # 如果存在，将标头添加到结果
     if headers:
         result['headers'] = headers
+
+    # Add cookies to the result if present
+    # 如果存在，将cookie添加到结果
     if cookies:
         result['cookies'] = cookies
+
+    # Handle request body data
+    # 处理请求正文数据
     if parsed_args.data:
         result['body'] = parsed_args.data
+
+        # If data is provided but method is not specified, default to POST
+        # 如果提供了数据但未指定方法，则默认为POST
         if not parsed_args.method:
             # if the "data" is specified but the "method" is not specified,
             # the default method is 'POST'

aioscrapy/utils/decorators.py

@@ -1,3 +1,13 @@
+"""
+Decorator utilities for aioscrapy.
+aioscrapy的装饰器实用工具。
+
+This module provides utility decorators for use in aioscrapy.
+It includes decorators for marking functions and methods as deprecated.
+此模块提供了在aioscrapy中使用的实用装饰器。
+它包括用于将函数和方法标记为已弃用的装饰器。
+"""
+
 import warnings
 from functools import wraps
 
@@ -5,21 +15,81 @@ from aioscrapy.exceptions import AioScrapyDeprecationWarning
 
 
 def deprecated(use_instead=None):
-    """This is a decorator which can be used to mark functions
-    as deprecated. It will result in a warning being emitted
-    when the function is used."""
+    """
+    Decorator to mark functions or methods as deprecated.
+    用于将函数或方法标记为已弃用的装饰器。
+
+    This decorator can be used to mark functions or methods as deprecated.
+    It will emit a warning when the decorated function is called, informing
+    users that the function is deprecated and suggesting an alternative if provided.
+    此装饰器可用于将函数或方法标记为已弃用。
+    当调用被装饰的函数时，它将发出警告，通知用户该函数已弃用，
+    并在提供替代方案时建议使用替代方案。
+
+    The decorator can be used in two ways:
+    装饰器可以通过两种方式使用：
+
+    1. With no arguments: @deprecated
+    2. With an argument specifying the alternative: @deprecated("new_function")
+
+    Args:
+        use_instead: Optional string indicating the alternative function or method to use.
+                    可选的字符串，指示要使用的替代函数或方法。
+                    Defaults to None.
+                    默认为None。
 
+    Returns:
+        callable: A decorated function that will emit a deprecation warning when called.
+                一个装饰后的函数，在调用时会发出弃用警告。
+
+    Example:
+        >>> @deprecated
+        ... def old_function():
+        ...     return "result"
+        ...
+        >>> @deprecated("new_improved_function")
+        ... def another_old_function():
+        ...     return "result"
+        ...
+        >>> # When called, these will emit warnings:
+        >>> old_function()  # Warning: "Call to deprecated function old_function."
+        >>> another_old_function()  # Warning: "Call to deprecated function another_old_function. Use new_improved_function instead."
+    """
+    # Handle case where decorator is used without arguments: @deprecated
+    # 处理装饰器不带参数使用的情况：@deprecated
+    if callable(use_instead):
+        # In this case, use_instead is actually the function being decorated
+        # 在这种情况下，use_instead实际上是被装饰的函数
+        func = use_instead
+        use_instead = None
+
+        # Apply the decorator directly and return the wrapped function
+        # 直接应用装饰器并返回包装后的函数
+        @wraps(func)
+        def wrapped(*args, **kwargs):
+            message = f"Call to deprecated function {func.__name__}."
+            warnings.warn(message, category=AioScrapyDeprecationWarning, stacklevel=2)
+            return func(*args, **kwargs)
+        return wrapped
+
+    # Handle case where decorator is used with an argument: @deprecated("new_function")
+    # 处理装饰器带参数使用的情况：@deprecated("new_function")
     def deco(func):
         @wraps(func)
         def wrapped(*args, **kwargs):
+            # Create the warning message
+            # 创建警告消息
             message = f"Call to deprecated function {func.__name__}."
             if use_instead:
                 message += f" Use {use_instead} instead."
+
+            # Emit the deprecation warning
+            # 发出弃用警告
             warnings.warn(message, category=AioScrapyDeprecationWarning, stacklevel=2)
+
+            # Call the original function
+            # 调用原始函数
             return func(*args, **kwargs)
         return wrapped
 
-    if callable(use_instead):
-        deco = deco(use_instead)
-        use_instead = None
     return deco

aioscrapy/utils/deprecate.py

@@ -1,4 +1,13 @@
-"""Some helpers for deprecation messages"""
+"""
+Deprecation utilities for aioscrapy.
+aioscrapy的弃用实用工具。
+
+This module provides utility functions and classes for handling deprecation in aioscrapy.
+It includes tools for creating deprecation warnings, creating deprecated classes,
+and updating class paths to their new locations.
+此模块提供了用于处理aioscrapy中弃用的实用函数和类。
+它包括用于创建弃用警告、创建已弃用类以及将类路径更新到其新位置的工具。
+"""
 
 import inspect
 import warnings
@@ -7,12 +16,51 @@ from aioscrapy.exceptions import AioScrapyDeprecationWarning
 
 
 def attribute(obj, oldattr, newattr, version='0.12'):
+    """
+    Issue a deprecation warning for an attribute that has been renamed.
+    为已重命名的属性发出弃用警告。
+
+    This function issues a deprecation warning when code accesses an old attribute
+    that has been renamed. It helps guide users to update their code to use the
+    new attribute name.
+    当代码访问已重命名的旧属性时，此函数会发出弃用警告。
+    它有助于指导用户更新其代码以使用新的属性名称。
+
+    Args:
+        obj: The object containing the deprecated attribute.
+             包含已弃用属性的对象。
+        oldattr: The name of the deprecated attribute.
+                已弃用属性的名称。
+        newattr: The name of the attribute that should be used instead.
+                应该使用的属性的名称。
+        version: The version of aioscrapy in which the old attribute will be removed.
+                将删除旧属性的aioscrapy版本。
+                Defaults to '0.12'.
+                默认为'0.12'。
+
+    Example:
+        >>> class MyClass:
+        ...     def __getattr__(self, name):
+        ...         if name == 'old_name':
+        ...             attribute(self, 'old_name', 'new_name')
+        ...             return self.new_name
+        ...         raise AttributeError(f"{self.__class__.__name__} has no attribute {name}")
+        ...
+        ...     @property
+        ...     def new_name(self):
+        ...         return "value"
+    """
+    # Get the class name of the object
+    # 获取对象的类名
     cname = obj.__class__.__name__
+
+    # Issue a deprecation warning with information about the old and new attributes
+    # 发出包含有关旧属性和新属性信息的弃用警告
     warnings.warn(
         f"{cname}.{oldattr} attribute is deprecated and will be no longer supported "
         f"in Aioscrapy {version}, use {cname}.{newattr} attribute instead",
         AioScrapyDeprecationWarning,
-        stacklevel=3)
+        stacklevel=3)  # Use stacklevel=3 to point to the caller's caller
 
 
 def create_deprecated_class(
@@ -27,28 +75,91 @@ def create_deprecated_class(
     instance_warn_message="{cls} is deprecated, instantiate {new} instead."
 ):
     """
-    Return a "deprecated" class that causes its subclasses to issue a warning.
-    Subclasses of ``new_class`` are considered subclasses of this class.
-    It also warns when the deprecated class is instantiated, but do not when
-    its subclasses are instantiated.
+    Create a deprecated class that redirects to a new class.
+    创建一个重定向到新类的已弃用类。
 
-    It can be used to rename a base class in a library. For example, if we
-    have
+    This function creates a "deprecated" class that issues warnings when:
+    1. A user subclasses from the deprecated class
+    2. A user instantiates the deprecated class directly
 
-        class OldName(SomeClass):
-            # ...
+    此函数创建一个"已弃用"类，在以下情况下发出警告：
+    1. 用户从已弃用的类继承
+    2. 用户直接实例化已弃用的类
 
-    and we want to rename it to NewName, we can do the following::
+    The deprecated class acts as a proxy to the new class, so:
+    - Subclasses of the new class are considered subclasses of the deprecated class
+    - isinstance() and issubclass() checks work as expected
+    - The deprecated class can be instantiated and will create instances of the new class
 
-        class NewName(SomeClass):
-            # ...
+    已弃用的类充当新类的代理，因此：
+    - 新类的子类被视为已弃用类的子类
+    - isinstance()和issubclass()检查按预期工作
+    - 可以实例化已弃用的类，它将创建新类的实例
 
-        OldName = create_deprecated_class('OldName', NewName)
+    This is particularly useful when renaming or moving classes in a library
+    while maintaining backward compatibility.
 
-    Then, if user class inherits from OldName, warning is issued. Also, if
-    some code uses ``issubclass(sub, OldName)`` or ``isinstance(sub(), OldName)``
-    checks they'll still return True if sub is a subclass of NewName instead of
-    OldName.
+    当在保持向后兼容性的同时重命名或移动库中的类时，这特别有用。
+
+    Args:
+        name: Name of the deprecated class.
+              已弃用类的名称。
+        new_class: The class that should be used instead.
+                  应该使用的类。
+        clsdict: Additional attributes to add to the deprecated class.
+                要添加到已弃用类的其他属性。
+                Defaults to None.
+                默认为None。
+        warn_category: Warning category to use.
+                      要使用的警告类别。
+                      Defaults to AioScrapyDeprecationWarning.
+                      默认为AioScrapyDeprecationWarning。
+        warn_once: Whether to warn only once when a subclass inherits from the deprecated class.
+                  当子类从已弃用的类继承时是否只警告一次。
+                  Defaults to True.
+                  默认为True。
+        old_class_path: Full import path of the old class (for better warning messages).
+                       旧类的完整导入路径（用于更好的警告消息）。
+                       Defaults to None.
+                       默认为None。
+        new_class_path: Full import path of the new class (for better warning messages).
+                       新类的完整导入路径（用于更好的警告消息）。
+                       Defaults to None.
+                       默认为None。
+        subclass_warn_message: Warning message template when a class inherits from the deprecated class.
+                              当类从已弃用的类继承时的警告消息模板。
+                              Defaults to "{cls} inherits from deprecated class {old}, please inherit from {new}.".
+                              默认为"{cls} inherits from deprecated class {old}, please inherit from {new}."。
+        instance_warn_message: Warning message template when the deprecated class is instantiated.
+                              当实例化已弃用的类时的警告消息模板。
+                              Defaults to "{cls} is deprecated, instantiate {new} instead.".
+                              默认为"{cls} is deprecated, instantiate {new} instead."。
+
+    Returns:
+        type: A deprecated class that proxies to the new class.
+              代理到新类的已弃用类。
+
+    Example:
+        >>> class OldName(SomeClass):
+        ...     # ...
+        ...
+        >>> class NewName(SomeClass):
+        ...     # ...
+        ...
+        >>> OldName = create_deprecated_class('OldName', NewName)
+        >>>
+        >>> # The following will issue a warning but still work:
+        >>> class UserClass(OldName):
+        ...     pass
+        ...
+        >>> # This will also issue a warning but create a NewName instance:
+        >>> instance = OldName()
+        >>>
+        >>> # These will return True:
+        >>> issubclass(UserClass, OldName)
+        >>> issubclass(UserClass, NewName)
+        >>> isinstance(instance, OldName)
+        >>> isinstance(instance, NewName)
     """
 
     class DeprecatedClass(new_class.__class__):
@@ -122,20 +233,102 @@ def create_deprecated_class(
 
 
 def _clspath(cls, forced=None):
+    """
+    Get the full import path of a class.
+    获取类的完整导入路径。
+
+    This internal helper function returns the full import path of a class
+    (module name + class name). It's used to generate informative deprecation
+    warning messages.
+    这个内部辅助函数返回类的完整导入路径（模块名+类名）。
+    它用于生成信息丰富的弃用警告消息。
+
+    Args:
+        cls: The class to get the path for.
+             要获取路径的类。
+        forced: An optional string to use instead of the actual class path.
+               可选的字符串，用于替代实际的类路径。
+               Defaults to None.
+               默认为None。
+
+    Returns:
+        str: The full import path of the class (e.g., 'package.module.ClassName')
+             or the forced path if provided.
+             类的完整导入路径（例如，'package.module.ClassName'）
+             或者如果提供了forced参数，则返回forced路径。
+    """
+    # If a forced path is provided, use it instead of calculating the path
+    # 如果提供了强制路径，则使用它而不是计算路径
     if forced is not None:
         return forced
+
+    # Otherwise, construct the path from the module and class name
+    # 否则，从模块和类名构造路径
     return f'{cls.__module__}.{cls.__name__}'
 
 
+# List of (prefix, replacement) tuples for updating deprecated class paths
+# Each rule specifies a prefix to match and its replacement for updating import paths
+# 用于更新已弃用类路径的(前缀, 替换)元组列表
+# 每个规则指定要匹配的前缀及其替换，用于更新导入路径
 DEPRECATION_RULES = []
 
 
 def update_classpath(path):
-    """Update a deprecated path from an object with its new location"""
+    """
+    Update a deprecated class path to its new location.
+    将已弃用的类路径更新到其新位置。
+
+    This function checks if a given import path matches any of the known
+    deprecated paths (defined in DEPRECATION_RULES) and returns the updated
+    path if a match is found. It also issues a deprecation warning.
+    此函数检查给定的导入路径是否匹配任何已知的已弃用路径
+    （在DEPRECATION_RULES中定义），如果找到匹配项，则返回更新的路径。
+    它还会发出弃用警告。
+
+    This is useful for handling cases where classes have been moved to
+    different modules or packages.
+    这对于处理类已移动到不同模块或包的情况很有用。
+
+    Args:
+        path: The import path to check and potentially update.
+              要检查和可能更新的导入路径。
+
+    Returns:
+        str: The updated path if the input path matches a deprecated path,
+             otherwise the original path.
+             如果输入路径匹配已弃用路径，则返回更新的路径，
+             否则返回原始路径。
+
+    Example:
+        >>> # Add a deprecation rule
+        >>> DEPRECATION_RULES.append(('old.module', 'new.module'))
+        >>>
+        >>> # This will return 'new.module.MyClass' and issue a warning
+        >>> update_classpath('old.module.MyClass')
+        'new.module.MyClass'
+        >>>
+        >>> # This will return the original path unchanged
+        >>> update_classpath('other.module.MyClass')
+        'other.module.MyClass'
+    """
+    # Check each deprecation rule to see if the path matches
+    # 检查每个弃用规则，看路径是否匹配
     for prefix, replacement in DEPRECATION_RULES:
+        # Only process string paths that start with the deprecated prefix
+        # 只处理以已弃用前缀开头的字符串路径
         if isinstance(path, str) and path.startswith(prefix):
+            # Replace the deprecated prefix with its replacement (only the first occurrence)
+            # 将已弃用的前缀替换为其替换（仅第一次出现）
             new_path = path.replace(prefix, replacement, 1)
+
+            # Issue a deprecation warning
+            # 发出弃用警告
             warnings.warn(f"`{path}` class is deprecated, use `{new_path}` instead",
                           AioScrapyDeprecationWarning)
+
             return new_path
+
+    # If no rules matched, return the original path unchanged
+    # 如果没有规则匹配，则原样返回原始路径
     return path