# Requests and Responses Scrapy uses [`Request`](#scrapy.Request) and [`Response`](#scrapy.http.Response) objects for crawling web sites. Typically, [`Request`](#scrapy.Request) objects are generated in the spiders and pass across the system until they reach the Downloader, which executes the request and returns a [`Response`](#scrapy.http.Response) object which travels back to the spider that issued the request. Both [`Request`](#scrapy.Request) and [`Response`](#scrapy.http.Response) classes have subclasses which add functionality not required in the base classes. These are described below in [Request subclasses](#topics-request-response-ref-request-subclasses) and [Response subclasses](#topics-request-response-ref-response-subclasses). ## Request objects ### *class* scrapy.Request(\*args: Any, \*\*kwargs: Any) Represents an HTTP request, which is usually generated in a Spider and executed by the Downloader, thus generating a [`Response`](#scrapy.http.Response). * **Parameters:** * **url** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – the URL of this request If the URL is invalid, a [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) exception is raised. * **callback** (*Callable* *[**Concatenate* *[*[*Response*](#scrapy.http.Response) *,* *...* *]* *,* *Any* *]* *|* *None*) – sets [`callback`](#scrapy.Request.callback), defaults to `None`. * **method** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – the HTTP method of this request. Defaults to `'GET'`. * **meta** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)) – the initial values for the [`Request.meta`](#scrapy.Request.meta) attribute. If given, the dict passed in this parameter will be shallow copied. * **body** ([*bytes*](https://docs.python.org/3/library/stdtypes.html#bytes) *or* [*str*](https://docs.python.org/3/library/stdtypes.html#str)) – the request body. If a string is passed, then it’s encoded as bytes using the `encoding` passed (which defaults to `utf-8`). If `body` is not given, an empty bytes object is stored. Regardless of the type of this argument, the final value stored will be a bytes object (never a string or `None`). * **headers** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)) – the headers of this request. The dict values can be strings (for single valued headers) or lists (for multi-valued headers). If `None` is passed as value, the HTTP header will not be sent at all. > [!CAUTION] > Cookies set via the `Cookie` header are not considered by the > [cookie middleware](cookies.md#cookies). If you need to set cookies for a > request, use the `cookies` argument. * **cookies** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict) *or* [*list*](https://docs.python.org/3/library/stdtypes.html#list)) – the request cookies, as a dict of cookie names and values or as a list of dicts with a cookie each. See [Cookies](cookies.md#cookies). * **encoding** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)) – the encoding of this request (defaults to `'utf-8'`). This encoding will be used to percent-encode the URL and to convert the body to bytes (if given as a string). To disable URL percent-encoding for a request, use the [`verbatim_url`](#std-reqmeta-verbatim_url) request meta key. * **priority** ([*int*](https://docs.python.org/3/library/functions.html#int)) – sets [`priority`](#scrapy.Request.priority), defaults to `0`. * **dont_filter** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – sets [`dont_filter`](#scrapy.Request.dont_filter), defaults to `False`. * **errback** (*Callable* *[* *[**Failure* *]* *,* *Any* *]* *|* *None*) – sets [`errback`](#scrapy.Request.errback), defaults to `None`. * **flags** ([*list*](https://docs.python.org/3/library/stdtypes.html#list)) – Flags sent to the request, can be used for logging or similar purposes. * **cb_kwargs** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)) – A dict with arbitrary data that will be passed as keyword arguments to the Request’s callback. #### url A string containing the URL of this request. Keep in mind that this attribute contains the escaped URL, so it can differ from the URL passed in the `__init__()` method. If [`verbatim_url`](#std-reqmeta-verbatim_url) is set to `True`, the URL is kept as passed to `__init__()`. This attribute is read-only. To change the URL of a Request use [`replace()`](#scrapy.Request.replace). #### method A string representing the HTTP method in the request. This is guaranteed to be uppercase. Example: `"GET"`, `"POST"`, `"PUT"`, etc #### headers A dictionary-like (`scrapy.http.headers.Headers`) object which contains the request headers. #### body The request body as bytes. This attribute is read-only. To change the body of a Request use [`replace()`](#scrapy.Request.replace). #### callback *: CallbackT | [None](https://docs.python.org/3/library/constants.html#None)* [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable) to parse the [`Response`](#scrapy.http.Response) to this request once received. The callable must expect the response as its first parameter, and support any additional keyword arguments set through [`cb_kwargs`](#scrapy.Request.cb_kwargs). See [Writing a callback](#writing-callbacks) and [Callback output](#callback-output). In addition to an arbitrary callable, the following values are also supported: - `None` (default), which indicates that the [`parse()`](spiders.md#scrapy.Spider.parse) method of the spider must be used. - [`NO_CALLBACK()`](#scrapy.http.request.NO_CALLBACK). If an unhandled exception is raised during request or response processing, i.e. by a [spider middleware](spider-middleware.md#topics-spider-middleware), [downloader middleware](downloader-middleware.md#topics-downloader-middleware) or download handler ([`DOWNLOAD_HANDLERS`](settings.md#std-setting-DOWNLOAD_HANDLERS)), [`errback`](#scrapy.Request.errback) is called instead. > [!TIP] > [`HttpErrorMiddleware`](spider-middleware.md#scrapy.spidermiddlewares.httperror.HttpErrorMiddleware) > raises exceptions for non-2xx responses by default, sending them > to the [`errback`](#scrapy.Request.errback) instead. > [!NOTE] > ### See also > > [Callbacks](#callbacks) #### errback *: Callable[[Failure], Any] | [None](https://docs.python.org/3/library/constants.html#None)* [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable) to handle exceptions raised during request or response processing. The callable must expect a [`Failure`](https://docs.twisted.org/en/stable/api/twisted.python.failure.Failure.html) as its first parameter. > [!NOTE] > ### See also > > [Errbacks](#errbacks) #### priority *: [int](https://docs.python.org/3/library/functions.html#int)* Default: `0` Value that the [scheduler](scheduler.md#topics-scheduler) may use for request prioritization. Built-in schedulers prioritize requests with a higher priority value. Negative values are allowed. #### cb_kwargs A dictionary that contains arbitrary metadata for this request. Its contents will be passed to the Request’s callback as keyword arguments. It is empty for new Requests, which means by default callbacks only get a [`Response`](#scrapy.http.Response) object as argument. This dict is [shallow copied](https://docs.python.org/3/library/copy.html) when the request is cloned using the `copy()` or `replace()` methods, and can also be accessed, in your spider, from the `response.cb_kwargs` attribute. In case of a failure to process the request, this dict can be accessed as `failure.request.cb_kwargs` in the request’s errback. For more information, see [Accessing additional data in errback functions](#errback-cb-kwargs). > [!NOTE] > When [`JOBDIR`](settings.md#std-setting-JOBDIR) is set, requests are serialized to disk > with [`pickle`](https://docs.python.org/3/library/pickle.html#module-pickle) (see [Request serialization](jobs.md#request-serialization)). As a result, > the callback receives a deep copy of any object stored in > `cb_kwargs`, so mutating such an object in the callback does not > affect the original. Avoid relying on shared mutable state passed > through `cb_kwargs` in that case. #### meta *= {}* > A dictionary of arbitrary metadata for the request. > You may extend request metadata as you see fit. > Request metadata can also be accessed through the > [`meta`](#scrapy.http.Response.meta) attribute of a response. > To pass your own data from one spider callback to another, use > [`cb_kwargs`](#scrapy.Request.cb_kwargs) instead, see [Passing additional data to callback functions](#callback-data). However, request > metadata may be the right choice in certain scenarios, such as to > maintain some debugging data across all follow-up requests (e.g. the > source URL). > A common use of request metadata is to define request-specific > parameters for Scrapy components (extensions, middlewares, etc.). For > example, if you set [`dont_retry`](downloader-middleware.md#std-reqmeta-dont_retry) to `True`, > [`RetryMiddleware`](downloader-middleware.md#scrapy.downloadermiddlewares.retry.RetryMiddleware) will never > retry that request, even if it fails. See [Request.meta special keys](#topics-request-meta). > You may also use request metadata in your custom Scrapy components, for > example, to keep request state information relevant to your component. > For example, > [`RetryMiddleware`](downloader-middleware.md#scrapy.downloadermiddlewares.retry.RetryMiddleware) uses the > [`retry_times`](downloader-middleware.md#std-reqmeta-retry_times) metadata key to keep track of how many times a > request has been retried so far. > Copying all the metadata of a previous request into a new, follow-up > request in a spider callback is a bad practice, because request > metadata may include metadata set by Scrapy components that is not > meant to be copied into other requests. For example, copying the > [`retry_times`](downloader-middleware.md#std-reqmeta-retry_times) metadata key into follow-up requests can lower > the amount of retries allowed for those follow-up requests. > You should only copy all request metadata from one request to another > if the new request is meant to replace the old request, as is often the > case when returning a request from a [downloader middleware](downloader-middleware.md#topics-downloader-middleware) method. > Also mind that the [`copy()`](#scrapy.Request.copy) and [`replace()`](#scrapy.Request.replace) request methods > [shallow-copy](https://docs.python.org/3/library/copy.html) request metadata. > > [!NOTE] > > ### See also > > > > [`MetaCopyDetectionMiddleware`](spider-middleware.md#scrapy.spidermiddlewares.metacopy.MetaCopyDetectionMiddleware) > > for a built-in middleware that warns about this issue at run time. #### dont_filter *: [bool](https://docs.python.org/3/library/functions.html#bool)* Whether this request may be filtered out by [components](components.md#topics-components) that support filtering out requests (`False`, default), or those components should not filter out this request (`True`). The following built-in components check this attribute: - The [scheduler](scheduler.md#topics-scheduler) uses it to skip duplicate request filtering (see [`DUPEFILTER_CLASS`](settings.md#std-setting-DUPEFILTER_CLASS)). When set to `True`, the request is not checked against the duplicate filter, allowing requests that would otherwise be considered duplicates to be scheduled multiple times. - [`OffsiteMiddleware`](downloader-middleware.md#scrapy.downloadermiddlewares.offsite.OffsiteMiddleware) uses it to allow requests to domains not in [`allowed_domains`](spiders.md#scrapy.Spider.allowed_domains). To skip only the offsite filter without affecting other components, consider using the [`allow_offsite`](downloader-middleware.md#std-reqmeta-allow_offsite) request meta key instead. Third-party components may also use this attribute to decide whether to filter out a request. When defining the start URLs of a spider through [`start_urls`](spiders.md#scrapy.Spider.start_urls), this attribute is enabled by default. See [`start()`](spiders.md#scrapy.Spider.start). #### attributes *: [tuple](https://docs.python.org/3/library/stdtypes.html#tuple)[[str](https://docs.python.org/3/library/stdtypes.html#str), ...]* *= ('url', 'headers', 'body', 'cookies', 'meta', 'encoding', 'flags', 'cb_kwargs', 'callback', 'dont_filter', 'errback', 'method', 'priority')* A tuple of [`str`](https://docs.python.org/3/library/stdtypes.html#str) objects containing the name of all public attributes of the class that are also keyword parameters of the `__init__()` method. Currently used by [`Request.replace()`](#scrapy.Request.replace), [`Request.to_dict()`](#scrapy.Request.to_dict) and [`request_from_dict()`](#scrapy.utils.request.request_from_dict). #### copy() Return a new Request which is a copy of this Request. See also: [Passing additional data to callback functions](#callback-data). #### replace([urlmethodheadersbodycookiesmetaflagsencodingprioritydont_filtercallbackerrbackcb_kwargscls], , , , , , , , , , , , ,) Return a Request object with the same members, except for those members given new values by whichever keyword arguments are specified. The [`cb_kwargs`](#scrapy.Request.cb_kwargs) and [`meta`](#scrapy.Request.meta) attributes are shallow copied by default (unless new values are given as arguments). See also [Passing additional data to callback functions](#callback-data). #### *classmethod* from_curl(curl_command: [str](https://docs.python.org/3/library/stdtypes.html#str), ignore_unknown_options: [bool](https://docs.python.org/3/library/functions.html#bool) = True, \*\*kwargs: Any) → Self Create a Request object from a string containing a [cURL](https://curl.se/) command. It populates the HTTP method, the URL, the headers, the cookies and the body. It accepts the same arguments as the [`Request`](#scrapy.Request) class, taking preference and overriding the values of the same arguments contained in the cURL command. Unrecognized options are ignored by default. To raise an error when finding unknown options call this method by passing `ignore_unknown_options=False`. > [!CAUTION] > Using [`from_curl()`](#scrapy.Request.from_curl) from [`Request`](#scrapy.Request) > subclasses, such as [`JsonRequest`](#scrapy.http.JsonRequest), or > `XmlRpcRequest`, as well as having > [downloader middlewares](downloader-middleware.md#topics-downloader-middleware) > and > [spider middlewares](spider-middleware.md#topics-spider-middleware) > enabled, such as > [`DefaultHeadersMiddleware`](downloader-middleware.md#scrapy.downloadermiddlewares.defaultheaders.DefaultHeadersMiddleware), > [`UserAgentMiddleware`](downloader-middleware.md#scrapy.downloadermiddlewares.useragent.UserAgentMiddleware), > or > [`HttpCompressionMiddleware`](downloader-middleware.md#scrapy.downloadermiddlewares.httpcompression.HttpCompressionMiddleware), > may modify the [`Request`](#scrapy.Request) object. To translate a cURL command into a Scrapy request, you may use [curl2scrapy](https://michael-shub.github.io/curl2scrapy/). #### to_curl() → [str](https://docs.python.org/3/library/stdtypes.html#str) Return a string with a [cURL](https://curl.se/) command equivalent to this request. Inverse of [`from_curl()`](#scrapy.Request.from_curl). See also `scrapy.utils.request.request_to_curl()`. > [!WARNING] > Added in version 2.18.0. #### to_dict(\*, spider: [Spider](spiders.md#scrapy.spiders.Spider) | [None](https://docs.python.org/3/library/constants.html#None) = None) → [dict](https://docs.python.org/3/library/stdtypes.html#dict)[[str](https://docs.python.org/3/library/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)] Return a dictionary containing the Request’s data. Use [`request_from_dict()`](#scrapy.utils.request.request_from_dict) to convert back into a [`Request`](#scrapy.Request) object. If a spider is given, this method will try to find out the name of the spider methods used as callback and errback and include them in the output dict, raising an exception if they cannot be found. ### Creating requests that submit HTML forms Use [form2request](https://form2request.readthedocs.io/en/latest/index.html) to build request data from an HTML `

` element and convert it to a [`Request`](#scrapy.Request). Install it with pip: ```bash pip install form2request ``` Select the desired form with CSS or XPath, then build and convert request data: ```python from form2request import form2request def parse(self, response): form = response.css("form#search") request_data = form2request(form, data={"q": "scrapy"}) yield request_data.to_scrapy(callback=self.parse_results) ``` Use `data` to override field values. To drop a field from the resulting request, set its value to `None`. By default, form2request simulates clicking the first submit button. To submit without clicking any button, pass `click=False`. To click a specific submit button, pass its element: ```python def parse(self, response): form = response.css("form#checkout") submit = form.css('button[name="pay"]') request_data = form2request(form, click=submit) ``` #### Using form2request to simulate a user login It is usual for web sites to provide pre-populated form fields through `` elements, such as session related data or authentication tokens (for login pages). Build the request from the form and only override the credentials: ```python import scrapy from form2request import form2request class LoginSpider(scrapy.Spider): name = "example.com" start_urls = ["http://www.example.com/users/login.php"] def parse(self, response): form = response.css("form") request_data = form2request( form, data={"username": "john", "password": "secret"}, ) yield request_data.to_scrapy(callback=self.after_login) def after_login(self, response): ... ``` ### Other functions related to requests ### scrapy.http.request.NO_CALLBACK(\*args: [Any](https://docs.python.org/3/library/typing.html#typing.Any), \*\*kwargs: [Any](https://docs.python.org/3/library/typing.html#typing.Any)) → [NoReturn](https://docs.python.org/3/library/typing.html#typing.NoReturn) When assigned to the `callback` parameter of [`Request`](#scrapy.Request), it indicates that the request is not meant to have a spider callback at all. For example: ```python Request("https://example.com", callback=NO_CALLBACK) ``` This value should be used by [components](components.md#topics-components) that create and handle their own requests, e.g. through `scrapy.core.engine.ExecutionEngine.download()`, so that downloader middlewares handling such requests can treat them differently from requests intended for the [`parse()`](spiders.md#scrapy.Spider.parse) callback. ### scrapy.utils.request.request_from_dict(d: [dict](https://docs.python.org/3/library/stdtypes.html#dict)[[str](https://docs.python.org/3/library/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)], \*, spider: [Spider](spiders.md#scrapy.spiders.Spider) | [None](https://docs.python.org/3/library/constants.html#None) = None) → [Request](#scrapy.Request) Create a [`Request`](#scrapy.Request) object from a dict. If a spider is given, it will try to resolve the callbacks looking at the spider for methods with the same name. ### scrapy.utils.httpobj.urlparse_cached(request_or_response: [Request](#scrapy.Request) | [Response](#scrapy.http.Response)) → ParseResult Return the result of parsing the URL of *request_or_response*, a [`Request`](#scrapy.Request) or [`Response`](#scrapy.http.Response) object, with [`urllib.parse.urlparse()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlparse). The result is cached, using a [`weakref.WeakKeyDictionary`](https://docs.python.org/3/library/weakref.html#weakref.WeakKeyDictionary) keyed on *request_or_response*, so that the URL of a given object is parsed only once. Prefer this function over calling [`urllib.parse.urlparse()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urlparse) on `request_or_response.url` directly when the same URL may be parsed more than once. ### Request fingerprints There are some aspects of scraping, such as filtering out duplicate requests (see [`DUPEFILTER_CLASS`](settings.md#std-setting-DUPEFILTER_CLASS)) or caching responses (see [`HTTPCACHE_POLICY`](downloader-middleware.md#std-setting-HTTPCACHE_POLICY)), where you need the ability to generate a short, unique identifier from a [`Request`](#scrapy.Request) object: a request fingerprint. You often do not need to worry about request fingerprints, the default request fingerprinter works for most projects. However, there is no universal way to generate a unique identifier from a request, because different situations require comparing requests differently. For example, sometimes you may need to compare URLs case-insensitively, include URL fragments, exclude certain URL query parameters, include some or all headers, etc. To change how request fingerprints are built for your requests, use the [`REQUEST_FINGERPRINTER_CLASS`](#std-setting-REQUEST_FINGERPRINTER_CLASS) setting. #### REQUEST_FINGERPRINTER_CLASS Default: [`scrapy.utils.request.RequestFingerprinter`](#scrapy.utils.request.RequestFingerprinter) A [request fingerprinter class](#custom-request-fingerprinter) or its import path. ### *class* scrapy.utils.request.RequestFingerprinter(crawler: [Crawler](api.md#scrapy.crawler.Crawler) | [None](https://docs.python.org/3/library/constants.html#None) = None) Default fingerprinter. It takes into account a canonical version ([`w3lib.url.canonicalize_url()`](https://w3lib.readthedocs.io/en/latest/w3lib.html#w3lib.url.canonicalize_url)) of [`request.url`](#scrapy.Request.url) and the values of [`request.method`](#scrapy.Request.method) and [`request.body`](#scrapy.Request.body), unless [`verbatim_url`](#std-reqmeta-verbatim_url) is true for that request. It then generates an [SHA1](https://en.wikipedia.org/wiki/SHA-1) hash. #### Writing your own request fingerprinter A request fingerprinter is a [component](components.md#topics-components) that must implement the following method: ### fingerprint(self, request: [scrapy.Request](#scrapy.Request)) Return a [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes) object that uniquely identifies *request*. See also [Request fingerprint restrictions](#request-fingerprint-restrictions). The [`fingerprint()`](#fingerprint) method of the default request fingerprinter, [`scrapy.utils.request.RequestFingerprinter`](#scrapy.utils.request.RequestFingerprinter), uses [`scrapy.utils.request.fingerprint()`](#scrapy.utils.request.fingerprint) with its default parameters. For some common use cases you can use [`scrapy.utils.request.fingerprint()`](#scrapy.utils.request.fingerprint) as well in your [`fingerprint()`](#fingerprint) method implementation: ### scrapy.utils.request.fingerprint(request: [Request](#scrapy.Request), \*, include_headers: Iterable[[bytes](https://docs.python.org/3/library/stdtypes.html#bytes) | [str](https://docs.python.org/3/library/stdtypes.html#str)] | [None](https://docs.python.org/3/library/constants.html#None) = None, keep_fragments: [bool](https://docs.python.org/3/library/functions.html#bool) = False) → [bytes](https://docs.python.org/3/library/stdtypes.html#bytes) Return the request fingerprint. The request fingerprint is a hash that uniquely identifies the resource the request points to. For example, take the following two urls: `http://www.example.com/query?id=111&cat=222`, `http://www.example.com/query?cat=222&id=111`. Even though those are two different URLs both point to the same resource and are equivalent (i.e. they should return the same response). Another example are cookies used to store session ids. Suppose the following page is only accessible to authenticated users: `http://www.example.com/members/offers.html`. Lots of sites use a cookie to store the session id, which adds a random component to the HTTP Request and thus should be ignored when calculating the fingerprint. For this reason, request headers are ignored by default when calculating the fingerprint. If you want to include specific headers use the include_headers argument, which is a list of Request headers to include. Also, servers usually ignore fragments in urls when handling requests, so they are also ignored by default when calculating the fingerprint. If you want to include them, set the keep_fragments argument to True (for instance when handling requests with a headless browser). keep_fragments is not a substitute for rendering JavaScript to reach content loaded based on the URL fragment; see [Selecting dynamically-loaded content](dynamic-content.md#topics-dynamic-content) for that instead. By default, request fingerprinting canonicalizes the request URL. If [`verbatim_url`](#std-reqmeta-verbatim_url) is set to `True`, fingerprinting does not canonicalize the URL, and the `keep_fragments` parameter is ignored (it is effectively true). For example, to take the value of a request header named `X-ID` into account: ```python # my_project/settings.py REQUEST_FINGERPRINTER_CLASS = "my_project.utils.RequestFingerprinter" # my_project/utils.py from scrapy.utils.request import fingerprint class RequestFingerprinter: def fingerprint(self, request): return fingerprint(request, include_headers=["X-ID"]) ``` You can also write your own fingerprinting logic from scratch. However, if you do not use [`scrapy.utils.request.fingerprint()`](#scrapy.utils.request.fingerprint), make sure you use [`WeakKeyDictionary`](https://docs.python.org/3/library/weakref.html#weakref.WeakKeyDictionary) to cache request fingerprints: - Caching saves CPU by ensuring that fingerprints are calculated only once per request, and not once per Scrapy component that needs the fingerprint of a request. - Using [`WeakKeyDictionary`](https://docs.python.org/3/library/weakref.html#weakref.WeakKeyDictionary) saves memory by ensuring that request objects do not stay in memory forever just because you have references to them in your cache dictionary. For example, to take into account only the URL of a request, without any prior URL canonicalization or taking the request method or body into account: ```python from hashlib import sha1 from weakref import WeakKeyDictionary from scrapy.utils.python import to_bytes class RequestFingerprinter: cache = WeakKeyDictionary() def fingerprint(self, request): if request not in self.cache: fp = sha1() fp.update(to_bytes(request.url)) self.cache[request] = fp.digest() return self.cache[request] ``` If you need to be able to override the request fingerprinting for arbitrary requests from your spider callbacks, you may implement a request fingerprinter that reads fingerprints from [`request.meta`](#scrapy.Request.meta) when available, and then falls back to [`scrapy.utils.request.fingerprint()`](#scrapy.utils.request.fingerprint). For example: ```python from scrapy.utils.request import fingerprint class RequestFingerprinter: def fingerprint(self, request): if "fingerprint" in request.meta: return request.meta["fingerprint"] return fingerprint(request) ``` If you need to reproduce the same fingerprinting algorithm as Scrapy 2.6, use the following request fingerprinter: ```python from hashlib import sha1 from weakref import WeakKeyDictionary from scrapy.utils.python import to_bytes from w3lib.url import canonicalize_url class RequestFingerprinter: cache = WeakKeyDictionary() def fingerprint(self, request): if request not in self.cache: fp = sha1() fp.update(to_bytes(request.method)) fp.update(to_bytes(canonicalize_url(request.url))) fp.update(request.body or b"") self.cache[request] = fp.digest() return self.cache[request] ``` #### Request fingerprint restrictions Scrapy components that use request fingerprints may impose additional restrictions on the format of the fingerprints that your [request fingerprinter](#custom-request-fingerprinter) generates. The following built-in Scrapy components have such restrictions: - [`scrapy.extensions.httpcache.FilesystemCacheStorage`](downloader-middleware.md#scrapy.extensions.httpcache.FilesystemCacheStorage) (default value of [`HTTPCACHE_STORAGE`](downloader-middleware.md#std-setting-HTTPCACHE_STORAGE)) Request fingerprints must be at least 1 byte long. Path and filename length limits of the file system of [`HTTPCACHE_DIR`](downloader-middleware.md#std-setting-HTTPCACHE_DIR) also apply. Inside [`HTTPCACHE_DIR`](downloader-middleware.md#std-setting-HTTPCACHE_DIR), the following directory structure is created: - [`Spider.name`](spiders.md#scrapy.Spider.name) - first byte of a request fingerprint as hexadecimal - fingerprint as hexadecimal - filenames up to 16 characters long For example, if a request fingerprint is made of 20 bytes (default), [`HTTPCACHE_DIR`](downloader-middleware.md#std-setting-HTTPCACHE_DIR) is `'/home/user/project/.scrapy/httpcache'`, and the name of your spider is `'my_spider'` your file system must support a file path like: ``` /home/user/project/.scrapy/httpcache/my_spider/01/0123456789abcdef0123456789abcdef01234567/response_headers ``` - [`scrapy.extensions.httpcache.DbmCacheStorage`](downloader-middleware.md#scrapy.extensions.httpcache.DbmCacheStorage) The underlying DBM implementation must support keys as long as twice the number of bytes of a request fingerprint, plus 5. For example, if a request fingerprint is made of 20 bytes (default), 45-character-long keys must be supported. ## Callbacks A callback is a function that Scrapy calls with the [`Response`](#scrapy.http.Response) of a [`Request`](#scrapy.Request) once that request has been downloaded, so that you can extract data from that response and generate additional requests to continue the crawl: ```python from scrapy import Request, Spider class BookSpider(Spider): name = "books" async def start(self): yield Request("https://books.toscrape.com/", callback=self.parse_home) def parse_home(self, response): for url in response.css("h3 a::attr(href)").getall(): yield Request(response.urljoin(url), callback=self.parse_book) def parse_book(self, response): yield {"title": response.css("h1::text").get()} ``` Requests may also define an [errback](#errbacks), which Scrapy calls instead of the callback when an exception is raised while processing the request or its response, e.g. a connection error or, by default, a non-2xx response. ### Assigning a callback to a request To assign a callback to a request, use the `callback` parameter of [`Request`](#scrapy.Request), which sets the [`Request.callback`](#scrapy.Request.callback) attribute: ```python from scrapy import Request def parse_home(response): ... request = Request("https://books.toscrape.com/", callback=parse_home) ``` Requests with no callback, i.e. with [`callback`](#scrapy.Request.callback) set to `None`, are handled by the [`parse()`](spiders.md#scrapy.Spider.parse) method of the spider: ```python request = Request("https://books.toscrape.com/") # Handled by parse() ``` If a request is never meant to reach a spider callback, e.g. because a [component](components.md#topics-components) sends it and handles its response itself, assign the special [`NO_CALLBACK()`](#scrapy.http.request.NO_CALLBACK) value to it instead, so that [downloader middlewares](downloader-middleware.md#topics-downloader-middleware) can tell such requests apart. While [`callback`](#scrapy.Request.callback) only accepts callables, some spider classes let you also define a callback by name: both [`CrawlSpider.rules`](spiders.md#scrapy.spiders.CrawlSpider.rules) and [`SitemapSpider.sitemap_rules`](spiders.md#scrapy.spiders.SitemapSpider.sitemap_rules) accept the name of a spider method as a string. ### Writing a callback Any callable can be a callback, as long as it takes the response as its first positional parameter, and any [additional callback data](#callback-data) as keyword parameters. Spider methods are the most common choice, but plain functions, lambda expressions and other callable objects work as well. > [!NOTE] > If you enable [job persistence](jobs.md#topics-jobs) through the > [`JOBDIR`](settings.md#std-setting-JOBDIR) setting, callbacks must be methods of the running spider. > Requests with any other callback cannot be serialized, so they are kept in > memory only and lost when you pause the crawl. See > [Request serialization](jobs.md#request-serialization). A callback can be: - A regular function: ```python def parse(self, response): return {"url": response.url} ``` - A generator function: ```python def parse(self, response): yield {"url": response.url} ``` - A coroutine function, i.e. defined with `async def`: ```python async def parse(self, response): return {"url": response.url} ``` - An asynchronous generator function: ```python async def parse(self, response): yield {"url": response.url} ``` The last two allow using `await`, `async for` and `async with` in your callback. See [Coroutines](coroutines.md#topics-coroutines). ### Callback output A callback may return or yield any of the following: - `None`, which does nothing. Callbacks that produce no output at all, e.g. callbacks that only log information about the response, are perfectly valid. `None` values within an iterable of callback output are ignored as well. - A [`Request`](#scrapy.Request) object, which Scrapy schedules, downloads and eventually sends to its own callback. - An [item object](items.md#topics-items), which Scrapy sends to the [item pipelines](item-pipeline.md#topics-item-pipeline). Any object that is neither `None` nor a [`Request`](#scrapy.Request) object is treated as an item. - An iterable of any of the values above, e.g. a list or, more commonly, a generator. [Asynchronous iterables](https://docs.python.org/3/glossary.html#term-asynchronous-iterable), e.g. an [asynchronous generator](https://docs.python.org/3/glossary.html#term-asynchronous-generator), are also supported. > [!NOTE] > When a callback *returns* an object, Scrapy iterates that object if > it supports iteration, except for [`dict`](https://docs.python.org/3/library/stdtypes.html#dict), [`Item`](items.md#scrapy.Item), > [`str`](https://docs.python.org/3/library/stdtypes.html#str) and [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes) objects, which are always handled as single > items. > [!NOTE] > In a generator callback, a `return` statement with a value does not > produce any output, since such a value is not part of what the generator > yields. Scrapy logs a warning when it detects such a callback, see > [`WARN_ON_GENERATOR_RETURN_VALUE`](settings.md#std-setting-WARN_ON_GENERATOR_RETURN_VALUE). Before Scrapy acts on the output of a callback, that output goes through the [`process_spider_output()`](spider-middleware.md#scrapy.spidermiddlewares.SpiderMiddleware.process_spider_output) method of your [spider middlewares](spider-middleware.md#topics-spider-middleware), which may modify it or drop part of it. If a callback raises an exception, the [`errback`](#scrapy.Request.errback) of the request is *not* called. The exception goes through the [`process_spider_exception()`](spider-middleware.md#scrapy.spidermiddlewares.SpiderMiddleware.process_spider_exception) method of your spider middlewares instead and, unless one of them handles it, Scrapy logs it and sends the [`spider_error`](signals.md#std-signal-spider_error) signal. ### Passing additional data to callback functions In some cases you may be interested in passing data to a callback in addition to the response, e.g. data extracted from the response that triggered the request. The following example shows how to achieve this by using the [`Request.cb_kwargs`](#scrapy.Request.cb_kwargs) attribute: ```python from scrapy import Request def parse(self, response): request = Request( "http://www.example.com/index.html", callback=self.parse_page2, cb_kwargs=dict(main_url=response.url), ) request.cb_kwargs["foo"] = "bar" # add more arguments for the callback yield request def parse_page2(self, response, main_url, foo): yield dict( main_url=main_url, other_url=response.url, foo=foo, ) ``` [`Request.cb_kwargs`](#scrapy.Request.cb_kwargs) is the recommended way to pass your own data to a callback. Use [`Request.meta`](#scrapy.Request.meta) only for data aimed at [components](components.md#topics-components), such as middlewares and extensions. ## Errbacks The errback of a request is a function that will be called when an exception is raised while processing it. It receives a [`Failure`](https://docs.twisted.org/en/stable/api/twisted.python.failure.Failure.html) as first parameter and can be used to track connection establishment timeouts, DNS errors etc. Scrapy sets the `request` attribute of that [`Failure`](https://docs.twisted.org/en/stable/api/twisted.python.failure.Failure.html) object to the [`Request`](#scrapy.Request) object being processed. If an errback raises an exception, Scrapy logs it and sends the [`spider_error`](signals.md#std-signal-spider_error) signal, unless the exception is the one that the errback received, which Scrapy logs as a download error instead. Here’s an example spider logging all errors and catching some specific errors if needed: ```python from scrapy import Request, Spider from scrapy.spidermiddlewares.httperror import HttpError from twisted.internet.error import DNSLookupError from twisted.internet.error import TimeoutError, TCPTimedOutError class ErrbackSpider(Spider): name = "errback_example" start_urls = [ "http://www.httpbin.org/", # HTTP 200 expected "http://www.httpbin.org/status/404", # Not found error "http://www.httpbin.org/status/500", # server issue "http://www.httpbin.org:12345/", # non-responding host, timeout expected "https://example.invalid/", # DNS error expected ] async def start(self): for u in self.start_urls: yield Request( u, callback=self.parse_httpbin, errback=self.errback_httpbin, dont_filter=True, ) def parse_httpbin(self, response): self.logger.info(f"Got successful response from {response.url}") # do something useful here... def errback_httpbin(self, failure): # log all failures self.logger.error(repr(failure)) # in case you want to do something special for some errors, # you may need the failure's type: if failure.check(HttpError): # these exceptions come from HttpError spider middleware # you can get the non-200 response response = failure.value.response self.logger.error("HttpError on %s", response.url) elif failure.check(DNSLookupError): # this is the original request request = failure.request self.logger.error("DNSLookupError on %s", request.url) elif failure.check(TimeoutError, TCPTimedOutError): request = failure.request self.logger.error("TimeoutError on %s", request.url) ``` ### Accessing additional data in errback functions In case of a failure to process the request, you may be interested in accessing arguments to the callback functions so you can process further based on the arguments in the errback. The following example shows how to achieve this by using `Failure.request.cb_kwargs`: ```python from scrapy import Request def parse(self, response): request = Request( "http://www.example.com/index.html", callback=self.parse_page2, errback=self.errback_page2, cb_kwargs=dict(main_url=response.url), ) yield request def parse_page2(self, response, main_url): pass def errback_page2(self, failure): yield dict( main_url=failure.request.cb_kwargs["main_url"], ) ``` ## Request.meta special keys The [`Request.meta`](#scrapy.Request.meta) attribute can contain any arbitrary data, but there are some special keys recognized by Scrapy and its built-in extensions. Those are: * [`allow_offsite`](downloader-middleware.md#std-reqmeta-allow_offsite) * [`autothrottle_dont_adjust_delay`](autothrottle.md#std-reqmeta-autothrottle_dont_adjust_delay) * [`bindaddress`](#std-reqmeta-bindaddress) * [`cache_timestamp`](downloader-middleware.md#std-reqmeta-cache_timestamp) * [`cookiejar`](cookies.md#std-reqmeta-cookiejar) * [`depth`](spider-middleware.md#std-reqmeta-depth) * [`dont_cache`](downloader-middleware.md#std-reqmeta-dont_cache) * [`dont_merge_cookies`](cookies.md#std-reqmeta-dont_merge_cookies) * [`dont_obey_robotstxt`](downloader-middleware.md#std-reqmeta-dont_obey_robotstxt) * [`dont_redirect`](downloader-middleware.md#std-reqmeta-dont_redirect) * [`dont_retry`](downloader-middleware.md#std-reqmeta-dont_retry) * [`download_fail_on_dataloss`](#std-reqmeta-download_fail_on_dataloss) * [`download_latency`](#std-reqmeta-download_latency) * [`download_maxsize`](settings.md#std-reqmeta-download_maxsize) * [`download_slot`](settings.md#std-reqmeta-download_slot) * [`download_timeout`](#std-reqmeta-download_timeout) * [`download_warnsize`](settings.md#std-reqmeta-download_warnsize) * [`ftp_local_filename`](#std-reqmeta-ftp_local_filename) * [`ftp_passive`](settings.md#std-reqmeta-ftp_passive) * [`ftp_password`](settings.md#std-reqmeta-ftp_password) * [`ftp_user`](settings.md#std-reqmeta-ftp_user) * [`give_up_log_level`](#std-reqmeta-give_up_log_level) * [`handle_httpstatus_all`](spider-middleware.md#std-reqmeta-handle_httpstatus_all) * [`handle_httpstatus_list`](spider-middleware.md#std-reqmeta-handle_httpstatus_list) * [`http_auth_domain`](#std-reqmeta-http_auth_domain) * [`http_pass`](#std-reqmeta-http_pass) * [`http_user`](#std-reqmeta-http_user) * [`is_start_request`](spider-middleware.md#std-reqmeta-is_start_request) * [`link_text`](spiders.md#std-reqmeta-link_text) * [`max_retry_times`](#std-reqmeta-max_retry_times) * [`priority_adjust`](downloader-middleware.md#std-reqmeta-priority_adjust) * [`proxy`](downloader-middleware.md#std-reqmeta-proxy) * [`redirect_reasons`](downloader-middleware.md#std-reqmeta-redirect_reasons) * [`redirect_times`](downloader-middleware.md#std-reqmeta-redirect_times) * [`redirect_ttl`](downloader-middleware.md#std-reqmeta-redirect_ttl) * [`redirect_urls`](downloader-middleware.md#std-reqmeta-redirect_urls) * [`referrer_policy`](spider-middleware.md#std-reqmeta-referrer_policy) * [`retry_times`](downloader-middleware.md#std-reqmeta-retry_times) * [`rule`](spiders.md#std-reqmeta-rule) * [`verbatim_url`](#std-reqmeta-verbatim_url) Scrapy components also use meta keys whose name starts with an underscore, such as `_auth_proxy`. Those are internal, and may change or disappear at any time. ### bindaddress The default local outgoing address for download-handler connections. This meta value can be either: - a host address as a string (e.g. `"127.0.0.2"`), in which case the local port is chosen automatically, or - a `(host, port)` tuple (e.g. `("127.0.0.2", 50000)`) to bind to both a specific local interface and a specific local port. For example: ```python Request( "https://example.org", meta={"bindaddress": "127.0.0.2"}, ) ``` ```python Request( "https://example.org", meta={"bindaddress": ("127.0.0.2", 50000)}, ) ``` If not set, built-in HTTP download handlers use the value of [`DOWNLOAD_BIND_ADDRESS`](settings.md#std-setting-DOWNLOAD_BIND_ADDRESS) as the default bind address. Set the [`bindaddress`](#std-reqmeta-bindaddress) request meta key to override it for a specific request. This meta key is not supported by [`HttpxDownloadHandler`](download-handlers.md#scrapy.core.downloader.handlers._httpx.HttpxDownloadHandler) and [`AiohttpDownloadHandler`](download-handlers.md#scrapy.core.downloader.handlers._aiohttp.AiohttpDownloadHandler), but the [`DOWNLOAD_BIND_ADDRESS`](settings.md#std-setting-DOWNLOAD_BIND_ADDRESS) setting is supported by them. ### download_timeout The amount of time (in secs) that the downloader will wait before timing out. See also: [`DOWNLOAD_TIMEOUT`](settings.md#std-setting-DOWNLOAD_TIMEOUT). ### download_latency The amount of time spent to fetch the response, since the request has been started, i.e. HTTP message sent over the network. This meta key only becomes available when the response has been downloaded. While most other meta keys are used to control Scrapy behavior, this one is supposed to be read-only. ### download_fail_on_dataloss Whether or not to fail on broken responses. See: [`DOWNLOAD_FAIL_ON_DATALOSS`](settings.md#std-setting-DOWNLOAD_FAIL_ON_DATALOSS). ### ftp_local_filename Path, as [`bytes`](https://docs.python.org/3/library/stdtypes.html#bytes), of the file where to write the response body of an `ftp://` request. If set, [`Response.body`](#scrapy.http.Response.body) holds this path instead of the file contents. ### give_up_log_level > [!WARNING] > Added in version 2.17.0. [Logging level](https://docs.python.org/3/library/logging.html#levels) used for the message logged when a request exceeds its retries. See [`RETRY_GIVE_UP_LOG_LEVEL`](downloader-middleware.md#std-setting-RETRY_GIVE_UP_LOG_LEVEL) for details. ### http_auth_domain > [!WARNING] > Added in version 2.17.0. Overrides [`HTTPAUTH_DOMAIN`](downloader-middleware.md#std-setting-HTTPAUTH_DOMAIN) for this request. ### http_pass > [!WARNING] > Added in version 2.17.0. Overrides [`HTTPAUTH_PASS`](downloader-middleware.md#std-setting-HTTPAUTH_PASS) for this request. ### http_user > [!WARNING] > Added in version 2.17.0. Overrides [`HTTPAUTH_USER`](downloader-middleware.md#std-setting-HTTPAUTH_USER) for this request. ### max_retry_times The meta key is used set retry times per request. When set, the [`max_retry_times`](#std-reqmeta-max_retry_times) meta key takes higher precedence over the [`RETRY_TIMES`](downloader-middleware.md#std-setting-RETRY_TIMES) setting. ### verbatim_url > [!WARNING] > Added in version 2.17.0. Set this key to `True` to keep the request URL as passed to [`Request`](#scrapy.Request), without URL percent-encoding. When this key is enabled, [`fingerprint()`](#scrapy.utils.request.fingerprint) does not canonicalize the request URL, so requests whose URLs differ only in characters that would otherwise be canonicalized get different fingerprints. In this mode, the `keep_fragments` parameter is ignored, and it is effectively true. ## Stopping the download of a Response Raising a [`StopDownload`](exceptions.md#scrapy.exceptions.StopDownload) exception from a handler for the [`bytes_received`](signals.md#scrapy.signals.bytes_received) or [`headers_received`](signals.md#scrapy.signals.headers_received) signals will stop the download of a given response. See the following example: ```python import scrapy class StopSpider(scrapy.Spider): name = "stop" start_urls = ["https://docs.scrapy.org/en/latest/"] @classmethod def from_crawler(cls, crawler): spider = super().from_crawler(crawler) crawler.signals.connect( spider.on_bytes_received, signal=scrapy.signals.bytes_received ) return spider def parse(self, response): # 'last_chars' show that the full response was not downloaded yield {"len": len(response.text), "last_chars": response.text[-40:]} def on_bytes_received(self, data, request, spider): raise scrapy.exceptions.StopDownload(fail=False) ``` which produces the following output: ``` 2020-05-19 17:26:12 [scrapy.core.engine] INFO: Spider opened 2020-05-19 17:26:12 [scrapy.extensions.logstats] INFO: Crawled 0 pages (at 0 pages/min), scraped 0 items (at 0 items/min) 2020-05-19 17:26:13 [scrapy.core.downloader.handlers.http11] DEBUG: Download stopped for from signal handler StopSpider.on_bytes_received 2020-05-19 17:26:13 [scrapy.core.engine] DEBUG: Crawled (200) (referer: None) ['download_stopped'] 2020-05-19 17:26:13 [scrapy.core.scraper] DEBUG: Scraped from <200 https://docs.scrapy.org/en/latest/> {'len': 279, 'last_chars': 'dth, initial-scale=1.0">\n \n