From 9dc9999eaa52e0afe038b48300336a21c81f9533 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Adri=C3=A1n=20Chaves?= <adrian@chaves.io>
Date: Tue, 1 Apr 2025 12:13:59 +0200
Subject: [PATCH] Add docs about universal start request definition

---
 docs/topics/spiders.rst    | 36 ++++++++++++++++++++++++++++++++++++
 scrapy/spiders/__init__.py | 14 +++++++++++---
 2 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/docs/topics/spiders.rst b/docs/topics/spiders.rst
index 1822ecbb6..d166bdda3 100644
--- a/docs/topics/spiders.rst
+++ b/docs/topics/spiders.rst
@@ -512,6 +512,42 @@ override the :meth:`~scrapy.Spider.start` method as follows:
 
 .. seealso:: :class:`~scrapy.crawler.Crawler`, :ref:`topics-signals`.
 
+Universal start request definition
+----------------------------------
+
+The :meth:`~scrapy.Spider.start` method was introduced in Scrapy VERSION. It
+replaced ``start_requests()``, which could be defined either as a synchronous
+:term:`generator` or as a synchronous method returning an
+:class:`~collections.abc.Iterable`.
+
+If you write spiders that must work with both Scrapy VERSION+ and lower
+versions, you must define both methods. For example:
+
+.. code-block:: python
+
+    from scrapy import Spider
+
+
+    class MySpider(Spider):
+        name = "myspider"
+
+        def start_requests(self):
+            yield Request("https://toscrape.com", headers={"Foo": "Bar"})
+
+        async def start(self):
+            for request in self.start_requests():
+                yield request
+
+Spiders that define both methods will not trigger a deprecation warning about
+``start_requests()``. When subclassing such a spider, if you override one of
+these methods, also override the other method, or you will get a warning.
+
+.. warning:: Do not call the ``start_requests()`` method of
+    :class:`~scrapy.Spider` or of other spider classes not defined by yourself
+    (e.g. using  ``super().start_requests()``) from your
+    :meth:`~scrapy.Spider.start` implementation. However, you can call your own
+    ``start_requests()`` method, as shown above.
+
 .. _builtin-spiders:
 
 Generic Spiders
diff --git a/scrapy/spiders/__init__.py b/scrapy/spiders/__init__.py
index 36d64b0a1..2a228a3c8 100644
--- a/scrapy/spiders/__init__.py
+++ b/scrapy/spiders/__init__.py
@@ -150,9 +150,17 @@ class Spider(object_ref):
         warnings.warn(
             (
                 "The Spider.start_requests() method is deprecated, use "
-                "Spider.start() instead. If you are calling "
-                "super().start_requests() from a Spider.start() override, "
-                "iterate super().start() instead."
+                "Spider.start() instead.\n"
+                "\n"
+                "If you are calling super().start_requests() from a "
+                "Spider.start() override, iterate super().start() instead.\n"
+                "\n"
+                "If you are calling super().start_requests() from a "
+                "Spider.start_requests() override, either redefine your "
+                "override to avoid a call to super().start_requests(), or use "
+                "warnings.catch_warnings() with warnings.filterwarnings() to "
+                "silence this warning (see the Spider.start() implementation "
+                "for an example)."
             ),
             ScrapyDeprecationWarning,
             stacklevel=2,