Documentation updates: playwright_suggested_filename meta key, Page type hints

Author: elacuesta

README.md

@@ -448,14 +448,16 @@ This key could be used in conjunction with `playwright_include_page` to make a c
 requests using the same page. For instance:
 
 ```python
+from playwright.async_api import Page
+
 def start_requests(self):
     yield scrapy.Request(
         url="https://httpbin.org/get",
         meta={"playwright": True, "playwright_include_page": True},
     )
 
 def parse(self, response, **kwargs):
-    page = response.meta["playwright_page"]
+    page: Page = response.meta["playwright_page"]
     yield scrapy.Request(
         url="https://httpbin.org/headers",
         callback=self.parse_headers,
@@ -496,6 +498,20 @@ def parse(self, response, **kwargs):
     # {'issuer': 'DigiCert TLS RSA SHA256 2020 CA1', 'protocol': 'TLS 1.3', 'subjectName': 'www.example.org', 'validFrom': 1647216000, 'validTo': 1678838399}
 ```
 
+### `playwright_suggested_filename`
+Type `Optional[str]`, read only
+
+The value of the [`Download.suggested_filename`](https://playwright.dev/python/docs/api/class-download#download-suggested-filename)
+attribute when the response is the binary contents of a
+[download](https://playwright.dev/python/docs/downloads) (e.g. a PDF file).
+Only available for responses that only caused a download. Can be accessed
+in the callback via `response.meta['playwright_suggested_filename']`
+
+```python
+def parse(self, response, **kwargs):
+    print(response.meta["playwright_suggested_filename"])
+    # 'sample_file.pdf'
+```
 
 ## Receiving Page objects in callbacks
 
@@ -514,6 +530,7 @@ necessary the spider job could get stuck because of the limit set by the
 `PLAYWRIGHT_MAX_PAGES_PER_CONTEXT` setting.
 
 ```python
+from playwright.async_api import Page
 import scrapy
 
 class AwesomeSpiderWithPage(scrapy.Spider):
@@ -528,7 +545,7 @@ class AwesomeSpiderWithPage(scrapy.Spider):
         )
 
     def parse_first(self, response):
-        page = response.meta["playwright_page"]
+        page: Page = response.meta["playwright_page"]
         return scrapy.Request(
             url="https://example.com",
             callback=self.parse_second,
@@ -537,13 +554,13 @@ class AwesomeSpiderWithPage(scrapy.Spider):
         )
 
     async def parse_second(self, response):
-        page = response.meta["playwright_page"]
+        page: Page = response.meta["playwright_page"]
         title = await page.title()  # "Example Domain"
         await page.close()
         return {"title": title}
 
     async def errback_close_page(self, failure):
-        page = failure.request.meta["playwright_page"]
+        page: Page = failure.request.meta["playwright_page"]
         await page.close()
 ```
 

examples/books.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 from typing import Generator, Optional
 
+from playwright.async_api import Page
 from scrapy import Spider
 from scrapy.http.response import Response
 
@@ -51,7 +52,7 @@ def parse(self, response: Response, current_page: Optional[int] = None) -> Gener
 
     async def parse_book(self, response: Response) -> dict:
         url_sha256 = hashlib.sha256(response.url.encode("utf-8")).hexdigest()
-        page = response.meta["playwright_page"]
+        page: Page = response.meta["playwright_page"]
         await page.screenshot(
             path=Path(__file__).parent / "books" / f"{url_sha256}.png", full_page=True
         )

examples/contexts.py

@@ -1,5 +1,6 @@
 from pathlib import Path
 
+from playwright.async_api import Page
 from scrapy import Spider, Request
 
 
@@ -96,7 +97,7 @@ def start_requests(self):
             )
 
     async def parse(self, response, **kwargs):
-        page = response.meta["playwright_page"]
+        page: Page = response.meta["playwright_page"]
         context_name = response.meta["playwright_context"]
         storage_state = await page.context.storage_state()
         await page.close()

examples/max_pages.py

@@ -1,3 +1,4 @@
+from playwright.async_api import Page
 from scrapy import Spider, Request
 
 
@@ -45,5 +46,5 @@ def parse(self, response, **kwargs):
         return {"url": response.url}
 
     async def errback(self, failure):
-        page = failure.request.meta["playwright_page"]
+        page: Page = failure.request.meta["playwright_page"]
         await page.close()

examples/storage.py

@@ -1,3 +1,4 @@
+from playwright.async_api import Page
 from scrapy import Spider, Request
 from scrapy_playwright.page import PageMethod
 
@@ -27,7 +28,7 @@ def start_requests(self):
         )
 
     async def parse(self, response, **kwargs):
-        page = response.meta["playwright_page"]
+        page: Page = response.meta["playwright_page"]
         storage_state = await page.context.storage_state()
         await page.close()
         return {