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

aioscrapy/exceptions.py

@@ -1,8 +1,6 @@
 """
 aioscrapy core exceptions
-
-These exceptions are documented in docs/topics/exceptions.rst. Please don't add
-new exceptions here without documenting them there.
+aioscrapy核心异常
 """
 
 
@@ -10,14 +8,23 @@ new exceptions here without documenting them there.
 
 
 class NotConfigured(Exception):
-    """Indicates a missing configuration situation"""
+    """
+    Indicates a missing configuration situation.
+    表示缺少配置的情况。
+
+    This exception is raised when a component or extension is not configured properly.
+    当组件或扩展未正确配置时，会引发此异常。
+    """
     pass
 
 
 class _InvalidOutput(TypeError):
     """
     Indicates an invalid value has been returned by a middleware's processing method.
+    表示中间件的处理方法返回了无效值。
+
     Internal and undocumented, it should not be raised or caught by user code.
+    内部使用且未记录，不应由用户代码引发或捕获。
     """
     pass
 
@@ -26,18 +33,47 @@ class _InvalidOutput(TypeError):
 
 
 class IgnoreRequest(Exception):
-    """Indicates a decision was made not to process a request"""
+    """
+    Indicates a decision was made not to process a request.
+    表示已决定不处理请求。
+
+    This exception can be raised by downloader middlewares to indicate that a request
+    should be ignored and not processed further.
+    下载器中间件可以引发此异常，以指示应忽略请求且不进一步处理。
+    """
 
 
 class DontCloseSpider(Exception):
-    """Request the spider not to be closed yet"""
+    """
+    Request the spider not to be closed yet.
+    请求不要立即关闭爬虫。
+
+    This exception can be raised in the spider_idle signal handler to prevent
+    the spider from being closed when it becomes idle.
+    可以在spider_idle信号处理程序中引发此异常，以防止爬虫在变为空闲状态时被关闭。
+    """
     pass
 
 
 class CloseSpider(Exception):
-    """Raise this from callbacks to request the spider to be closed"""
+    """
+    Raise this from callbacks to request the spider to be closed.
+    从回调中引发此异常以请求关闭爬虫。
+
+    This exception can be raised from a spider callback to request the spider to be
+    closed with a specific reason.
+    可以从爬虫回调中引发此异常，以请求以特定原因关闭爬虫。
+    """
 
     def __init__(self, reason='cancelled'):
+        """
+        Initialize the exception with a reason.
+        使用原因初始化异常。
+
+        Args:
+            reason: The reason for closing the spider. Default is 'cancelled'.
+                   关闭爬虫的原因。默认为'cancelled'。
+        """
         super().__init__()
         self.reason = reason
 
@@ -45,11 +81,30 @@ class CloseSpider(Exception):
 class StopDownload(Exception):
     """
     Stop the download of the body for a given response.
+    停止给定响应的正文下载。
+
     The 'fail' boolean parameter indicates whether or not the resulting partial response
     should be handled by the request errback. Note that 'fail' is a keyword-only argument.
+    'fail'布尔参数指示是否应由请求的errback处理结果部分响应。请注意，'fail'是仅关键字参数。
+
+    This exception can be raised during the download process to stop downloading
+    the response body, for example when only the headers are needed.
+    可以在下载过程中引发此异常以停止下载响应正文，例如当只需要头信息时。
     """
 
     def __init__(self, *, fail=True):
+        """
+        Initialize the exception.
+        初始化异常。
+
+        Args:
+            fail: Whether the partial response should be treated as a failure.
+                 部分响应是否应被视为失败。
+                 If True, the request's errback will be called.
+                 如果为True，将调用请求的errback。
+                 If False, the request's callback will be called with the partial response.
+                 如果为False，将使用部分响应调用请求的callback。
+        """
         super().__init__()
         self.fail = fail
 
@@ -58,12 +113,26 @@ class StopDownload(Exception):
 
 
 class DropItem(Exception):
-    """Drop item from the item pipeline"""
+    """
+    Drop item from the item pipeline.
+    从项目管道中丢弃项目。
+
+    This exception can be raised by item pipeline components to indicate that an item
+    should not be processed further and should be dropped.
+    项目管道组件可以引发此异常，以指示不应进一步处理项目并应将其丢弃。
+    """
     pass
 
 
 class NotSupported(Exception):
-    """Indicates a feature or method is not supported"""
+    """
+    Indicates a feature or method is not supported.
+    表示不支持某个功能或方法。
+
+    This exception is raised when attempting to use a feature or method that is
+    not supported by the current implementation or configuration.
+    当尝试使用当前实现或配置不支持的功能或方法时，会引发此异常。
+    """
     pass
 
 
@@ -71,37 +140,106 @@ class NotSupported(Exception):
 
 
 class UsageError(Exception):
-    """To indicate a command-line usage error"""
+    """
+    To indicate a command-line usage error.
+    表示命令行使用错误。
+
+    This exception is raised when a command-line tool is used incorrectly,
+    with invalid arguments or options.
+    当命令行工具使用不正确、带有无效参数或选项时，会引发此异常。
+    """
 
     def __init__(self, *a, **kw):
+        """
+        Initialize the exception.
+        初始化异常。
+
+        Args:
+            *a: Positional arguments for the exception message.
+                异常消息的位置参数。
+            **kw: Keyword arguments. Special keyword 'print_help' controls whether
+                  to print help information when the exception is caught.
+                  关键字参数。特殊关键字'print_help'控制在捕获异常时是否打印帮助信息。
+        """
         self.print_help = kw.pop('print_help', True)
         super().__init__(*a, **kw)
 
 
 class AioScrapyDeprecationWarning(Warning):
-    """Warning category for deprecated features, since the default
+    """
+    Warning category for deprecated features, since the default
     DeprecationWarning is silenced on Python 2.7+
+    已弃用功能的警告类别，因为默认的DeprecationWarning在Python 2.7+上被静默。
+
+    This warning is used to indicate that a feature or API is deprecated and will be
+    removed in a future version of aioscrapy.
+    此警告用于指示某个功能或API已弃用，并将在aioscrapy的未来版本中删除。
     """
     pass
 
 
 class ContractFail(AssertionError):
-    """Error raised in case of a failing contract"""
+    """
+    Error raised in case of a failing contract.
+    在合约失败的情况下引发的错误。
+
+    This exception is raised when a spider contract fails during testing.
+    当爬虫合约在测试期间失败时，会引发此异常。
+    Spider contracts are used to test the behavior of spiders.
+    爬虫合约用于测试爬虫的行为。
+    """
     pass
 
 
 class ProxyException(Exception):
+    """
+    Exception related to proxy usage.
+    与代理使用相关的异常。
+
+    This exception is raised when there is an issue with proxy configuration,
+    connection, or authentication.
+    当代理配置、连接或认证出现问题时，会引发此异常。
+    """
     pass
 
 
 class DownloadError(Exception):
-    """下载页面时发生的错误"""
+    """
+    Error that occurs when downloading a page.
+    下载页面时发生的错误。
+
+    This exception wraps the original error that occurred during the download process,
+    providing additional context and formatting.
+    此异常包装了下载过程中发生的原始错误，提供额外的上下文和格式化。
+    """
 
     def __init__(self, *args, real_error=None):
+        """
+        Initialize the exception.
+        初始化异常。
+
+        Args:
+            *args: Positional arguments for the exception message.
+                  异常消息的位置参数。
+            real_error: The original error that caused the download to fail.
+                       导致下载失败的原始错误。
+        """
         self.real_error = real_error
         super().__init__(*args)
 
     def __str__(self):
+        """
+        Return a string representation of the exception.
+        返回异常的字符串表示。
+
+        If there is a real error, returns a string in the format:
+        如果有真实错误，则返回格式为：
+        "module.ErrorClass: error message"
+
+        Returns:
+            String representation of the exception.
+            异常的字符串表示。
+        """
         if not self.real_error:
             return "DownloadError"
 

aioscrapy/http/__init__.py

@@ -10,6 +10,6 @@ from aioscrapy.http.request.form import FormRequest
 from aioscrapy.http.request.json_request import JsonRequest
 from aioscrapy.http.response import Response
 from aioscrapy.http.response.html import HtmlResponse
-from aioscrapy.http.response.playwright import PlaywrightResponse
+from aioscrapy.http.response.web_driver import WebDriverResponse
 from aioscrapy.http.response.text import TextResponse
 from aioscrapy.http.response.xml import XmlResponse

aioscrapy/http/headers.py

@@ -1,57 +1,291 @@
+"""
+HTTP headers implementation for aioscrapy.
+aioscrapy的HTTP头部实现。
+
+This module provides the Headers class, which is a case-insensitive dictionary
+specifically designed for handling HTTP headers. It normalizes header names
+to title case for consistent access regardless of the original casing.
+此模块提供了Headers类，这是一个专门为处理HTTP头部设计的大小写不敏感的字典。
+它将头部名称规范化为标题大小写，以便无论原始大小写如何都能一致地访问。
+"""
+
 from collections.abc import Mapping
 
 
 class Headers(dict):
-    """Case insensitive http headers dictionary"""
+    """
+    Case insensitive HTTP headers dictionary.
+    大小写不敏感的HTTP头部字典。
+
+    This class extends the built-in dict to provide a case-insensitive
+    dictionary specifically for HTTP headers. Header names are normalized
+    to title case (e.g., 'content-type' becomes 'Content-Type') for
+    consistent access regardless of the original casing.
+    此类扩展了内置的dict，为HTTP头部提供了一个大小写不敏感的字典。
+    头部名称被规范化为标题大小写（例如，'content-type'变为'Content-Type'），
+    以便无论原始大小写如何都能一致地访问。
 
+    Example:
+        ```python
+        headers = Headers({'content-type': 'text/html'})
+        assert headers['Content-Type'] == 'text/html'
+        assert headers['CONTENT-TYPE'] == 'text/html'
+        assert headers['content-type'] == 'text/html'
+        ```
+    """
+
+    # Use __slots__ to optimize memory usage
+    # 使用__slots__优化内存使用
     __slots__ = ()
 
     def __init__(self, seq=None):
+        """
+        Initialize a Headers dictionary.
+        初始化Headers字典。
+
+        Args:
+            seq: An optional sequence of key-value pairs or a mapping to initialize the dictionary.
+                一个可选的键值对序列或映射，用于初始化字典。
+        """
         super().__init__()
         if seq:
             self.update(seq)
 
     def __getitem__(self, key):
+        """
+        Get a header value by key.
+        通过键获取头部值。
+
+        The key is normalized to title case before lookup.
+        在查找之前，键会被规范化为标题大小写。
+
+        Args:
+            key: The header name.
+                头部名称。
+
+        Returns:
+            The header value.
+            头部值。
+
+        Raises:
+            KeyError: If the header is not found.
+                     如果未找到头部。
+        """
         return dict.__getitem__(self, self.normkey(key))
 
     def __setitem__(self, key, value):
+        """
+        Set a header value.
+        设置头部值。
+
+        The key is normalized to title case and the value is normalized
+        before being stored.
+        在存储之前，键会被规范化为标题大小写，值也会被规范化。
+
+        Args:
+            key: The header name.
+                头部名称。
+            value: The header value.
+                  头部值。
+        """
         dict.__setitem__(self, self.normkey(key), self.normvalue(value))
 
     def __delitem__(self, key):
+        """
+        Delete a header.
+        删除头部。
+
+        The key is normalized to title case before lookup.
+        在查找之前，键会被规范化为标题大小写。
+
+        Args:
+            key: The header name.
+                头部名称。
+
+        Raises:
+            KeyError: If the header is not found.
+                     如果未找到头部。
+        """
         dict.__delitem__(self, self.normkey(key))
 
     def __contains__(self, key):
+        """
+        Check if a header exists.
+        检查头部是否存在。
+
+        The key is normalized to title case before lookup.
+        在查找之前，键会被规范化为标题大小写。
+
+        Args:
+            key: The header name.
+                头部名称。
+
+        Returns:
+            bool: True if the header exists, False otherwise.
+                 如果头部存在则为True，否则为False。
+        """
         return dict.__contains__(self, self.normkey(key))
 
+    # Alias for backward compatibility
+    # 为了向后兼容的别名
     has_key = __contains__
 
     def __copy__(self):
+        """
+        Create a copy of the Headers dictionary.
+        创建Headers字典的副本。
+
+        Returns:
+            Headers: A new Headers instance with the same contents.
+                    具有相同内容的新Headers实例。
+        """
         return self.__class__(self)
 
+    # Alias for standard dict interface
+    # 标准dict接口的别名
     copy = __copy__
 
     def normkey(self, key):
-        """Method to normalize dictionary key access"""
+        """
+        Normalize a dictionary key for case-insensitive access.
+        规范化字典键以进行大小写不敏感的访问。
+
+        This method converts the key to title case (e.g., 'content-type' becomes 'Content-Type').
+        此方法将键转换为标题大小写（例如，'content-type'变为'Content-Type'）。
+
+        Args:
+            key: The header name to normalize.
+                要规范化的头部名称。
+
+        Returns:
+            str: The normalized header name.
+                规范化的头部名称。
+        """
         return key.title()
 
     def normvalue(self, value):
-        """Method to normalize values prior to be setted"""
+        """
+        Normalize a value before setting it in the dictionary.
+        在将值设置到字典中之前对其进行规范化。
+
+        This method is a hook for subclasses to override. The base implementation
+        returns the value unchanged.
+        此方法是供子类重写的钩子。基本实现返回未更改的值。
+
+        Args:
+            value: The header value to normalize.
+                  要规范化的头部值。
+
+        Returns:
+            The normalized header value.
+            规范化的头部值。
+        """
         return value
 
     def get(self, key, def_val=None):
+        """
+        Get a header value by key, with a default value if not found.
+        通过键获取头部值，如果未找到则返回默认值。
+
+        The key is normalized to title case and the default value is normalized
+        before lookup.
+        在查找之前，键会被规范化为标题大小写，默认值也会被规范化。
+
+        Args:
+            key: The header name.
+                头部名称。
+            def_val: The default value to return if the header is not found.
+                    如果未找到头部，则返回的默认值。
+
+        Returns:
+            The header value if found, otherwise the default value.
+            如果找到头部值则返回它，否则返回默认值。
+        """
         return dict.get(self, self.normkey(key), self.normvalue(def_val))
 
     def setdefault(self, key, def_val=None):
+        """
+        Get a header value by key, or set it to a default value if not found.
+        通过键获取头部值，如果未找到则将其设置为默认值。
+
+        The key is normalized to title case and the default value is normalized
+        before lookup or insertion.
+        在查找或插入之前，键会被规范化为标题大小写，默认值也会被规范化。
+
+        Args:
+            key: The header name.
+                头部名称。
+            def_val: The default value to set and return if the header is not found.
+                    如果未找到头部，则设置并返回的默认值。
+
+        Returns:
+            The header value if found, otherwise the default value.
+            如果找到头部值则返回它，否则返回默认值。
+        """
         return dict.setdefault(self, self.normkey(key), self.normvalue(def_val))
 
     def update(self, seq):
+        """
+        Update the dictionary with new headers.
+        使用新头部更新字典。
+
+        The keys and values are normalized before insertion.
+        在插入之前，键和值会被规范化。
+
+        Args:
+            seq: A sequence of key-value pairs or a mapping to update the dictionary with.
+                用于更新字典的键值对序列或映射。
+        """
+        # Convert mapping to items() if necessary
+        # 如果需要，将映射转换为items()
         seq = seq.items() if isinstance(seq, Mapping) else seq
+
+        # Normalize keys and values
+        # 规范化键和值
         iseq = ((self.normkey(k), self.normvalue(v)) for k, v in seq)
+
+        # Update the dictionary
+        # 更新字典
         super().update(iseq)
 
     @classmethod
     def fromkeys(cls, keys, value=None):
+        """
+        Create a new Headers dictionary with the specified keys and value.
+        使用指定的键和值创建一个新的Headers字典。
+
+        Args:
+            keys: An iterable of keys.
+                 键的可迭代对象。
+            value: The value to set for all keys.
+                  为所有键设置的值。
+
+        Returns:
+            Headers: A new Headers instance with the specified keys and value.
+                    具有指定键和值的新Headers实例。
+        """
         return cls((k, value) for k in keys)
 
     def pop(self, key, *args):
+        """
+        Remove a header and return its value.
+        移除头部并返回其值。
+
+        The key is normalized to title case before lookup.
+        在查找之前，键会被规范化为标题大小写。
+
+        Args:
+            key: The header name.
+                头部名称。
+            *args: Optional default value to return if the header is not found.
+                  如果未找到头部，则返回的可选默认值。
+
+        Returns:
+            The header value if found, otherwise the default value.
+            如果找到头部值则返回它，否则返回默认值。
+
+        Raises:
+            KeyError: If the header is not found and no default value is provided.
+                     如果未找到头部且未提供默认值。
+        """
         return dict.pop(self, self.normkey(key), *args)