refactor!: mark secondary arguments as keyword-only (#2318)

Secondary arguments across the public API are now keyword-only, the same
way as in apify/apify-client-python#766. The main argument of each call
(key, value, data, selector, path) stays positional. Named call sites
read better, and new options can go anywhere in a signature without
breaking existing callers.

The full list is in the v2 upgrade guide. It covers the context helpers
(`push_data`, `add_requests`, `block_requests`),
`BasicCrawler.get_data`/`export_data`, `KeyValueStore.set_value` and the
key iterators, `Dataset.export_to`, `ConcurrencySettings`,
`RequestList`, `ProxyConfiguration.new_url`/`new_proxy_info`, the
adaptive crawler factories and selector helpers,
`HeaderGenerator.get_specific_headers`, `BrowserController.new_page`,
`PlaywrightPersistentBrowser` and `find_links` on the parsers.
`KeyValueStore.get_value` keeps `default_value` positional to match
Crawlee JS. The three arguments of `new_proxy_info` now default to
`None`, as on `new_url`.

Closes: #1863

*✍️ Drafted by Claude Code*

Author: vdusek

docs/examples/code_examples/adaptive_playwright_crawler.py

@@ -26,7 +26,7 @@ async def request_handler_for_label(
         context.log.info(context.parsed_content.title)
 
         # Locate element h2 within 5 seconds
-        h2 = await context.query_selector_one('h2', timedelta(milliseconds=5000))
+        h2 = await context.query_selector_one('h2', timeout=timedelta(milliseconds=5000))
         # Do stuff with element found by the selector
         context.log.info(h2)
 

docs/guides/code_examples/http_crawlers/selectolax_parser.py

@@ -45,7 +45,7 @@ def is_matching_selector(
 
     @override
     def find_links(
-        self, parsed_content: LexborHTMLParser, selector: str, attribute: str
+        self, parsed_content: LexborHTMLParser, selector: str, *, attribute: str
     ) -> Iterable[str]:
         """Extract href attributes from elements matching the selector.
 

docs/guides/code_examples/playwright_crawler_adaptive/handler.py

@@ -10,7 +10,7 @@ async def main() -> None:
     @crawler.router.default_handler
     async def request_handler(context: AdaptivePlaywrightCrawlingContext) -> None:
         # Locate element h2 within 5 seconds
-        h2 = await context.query_selector_one('h2', timedelta(milliseconds=5000))
+        h2 = await context.query_selector_one('h2', timeout=timedelta(milliseconds=5000))
         # Do stuff with element found by the selector
         context.log.info(h2)
 

docs/upgrading/upgrading_to_v2.md

@@ -20,3 +20,37 @@ We drop support for Python 3.10, which reached its end of life in October 2026.
 ## `RequestQueueClient.is_finished` is abstract
 
 `RequestQueueClient.is_finished` is now an abstract method. In v1, it fell back to `is_empty`, which ignores requests still being processed and could report the queue as finished too early. A subclass that doesn't implement it raises `TypeError` on instantiation. If you have a custom request queue client, implement `is_finished` so that it returns `True` only when the queue is empty and no requests are in progress. The built-in clients already implement it.
+
+## Keyword-only arguments
+
+Secondary arguments of the public API are now keyword-only. The main argument of each call, such as a key, a value, a selector or a path, stays positional. A call that passes any of the following arguments positionally raises `TypeError`, so pass them by name:
+
+- `context.push_data(data, *, dataset_id, dataset_name, dataset_alias)`, and the same for `RequestHandlerRunResult.push_data`.
+- `context.add_requests(requests, *, rq_id, rq_name, rq_alias)`, and the same for `RequestHandlerRunResult.add_requests`.
+- `context.block_requests(*, url_patterns, extra_url_patterns)`, and `block_requests(page, *, url_patterns, extra_url_patterns)`.
+- `BasicCrawlingContext.create_modified_copy(*, push_data, add_requests, get_key_value_store)`.
+- `BasicCrawler.get_data(*, dataset_id, dataset_name, dataset_alias, ...)` and `BasicCrawler.export_data(path, *, dataset_id, dataset_name, dataset_alias, ...)`.
+- `KeyValueStore.set_value(key, value, *, content_type)`, also on the key-value store returned by `context.get_key_value_store()`.
+- `KeyValueStore.iterate_keys`, `iterate_values`, `iterate_entries` and `list_keys`, which take `exclusive_start_key` and `limit` by keyword only.
+- `Dataset.export_to(key, *, content_type, to_kvs_id, ...)`.
+- `ConcurrencySettings(*, min_concurrency, max_concurrency, max_tasks_per_minute, desired_concurrency)`.
+- `RequestList(requests, *, name, persist_state_key, persist_requests_key)`.
+- `ProxyConfiguration.new_url(*, session_id, request, proxy_tier)` and `ProxyConfiguration.new_proxy_info(*, session_id, request, proxy_tier)`. All three arguments of `new_proxy_info` now default to `None`.
+- `AdaptivePlaywrightCrawler.with_beautifulsoup_static_parser(*, ...)` and `with_parsel_static_parser(*, ...)`.
+- `AdaptivePlaywrightCrawlingContext.wait_for_selector`, `query_selector_one`, `query_selector_all` and `parse_with_static_parser`, which take `timeout` by keyword only.
+- `HeaderGenerator.get_specific_headers(header_names, *, browser_type)`.
+- `BrowserController.new_page(*, browser_new_context_options, proxy_info)`, including the Playwright and Stagehand controllers.
+- `PlaywrightPersistentBrowser(browser_type, user_data_dir, *, browser_launch_options)`.
+- `AbstractHttpParser.find_links(parsed_content, selector, *, attribute)`, including the built-in parsers. Custom parsers keep working, since the crawler passes `attribute` by keyword.
+
+For example:
+
+```python
+# v1
+await kvs.set_value('report', data, 'application/json')
+h2 = await context.query_selector_one('h2', timedelta(seconds=5))
+
+# v2
+await kvs.set_value('report', data, content_type='application/json')
+h2 = await context.query_selector_one('h2', timeout=timedelta(seconds=5))
+```

src/crawlee/_types.py

@@ -106,6 +106,7 @@ class ConcurrencySettings:
 
     def __init__(
         self,
+        *,
         min_concurrency: int = 1,
         max_concurrency: int = 100,
         max_tasks_per_minute: float = float('inf'),
@@ -223,6 +224,7 @@ async def set_value(
         self,
         key: str,
         value: Any,
+        *,
         content_type: str | None = None,
     ) -> None: ...
 
@@ -242,6 +244,7 @@ async def set_value(
         self,
         key: str,
         value: Any,
+        *,
         content_type: str | None = None,
     ) -> None:
         self.updates[key] = KeyValueStoreValue(value, content_type)
@@ -278,6 +281,7 @@ def __init__(
     async def add_requests(
         self,
         requests: Sequence[str | Request],
+        *,
         rq_id: str | None = None,
         rq_name: str | None = None,
         rq_alias: str | None = None,
@@ -294,6 +298,7 @@ async def add_requests(
     async def push_data(
         self,
         data: Sequence[Mapping[str, JsonSerializable]] | Mapping[str, JsonSerializable],
+        *,
         dataset_id: str | None = None,
         dataset_name: str | None = None,
         dataset_alias: str | None = None,
@@ -336,6 +341,7 @@ class AddRequestsFunction(Protocol):
     def __call__(
         self,
         requests: Sequence[str | Request],
+        *,
         rq_id: str | None = None,
         rq_name: str | None = None,
         rq_alias: str | None = None,
@@ -538,6 +544,7 @@ class PushDataFunction(Protocol):
     def __call__(
         self,
         data: Sequence[Mapping[str, JsonSerializable]] | Mapping[str, JsonSerializable],
+        *,
         dataset_id: str | None = None,
         dataset_name: str | None = None,
         dataset_alias: str | None = None,
@@ -673,6 +680,7 @@ def __hash__(self) -> int:
 
     def create_modified_copy(
         self,
+        *,
         push_data: PushDataFunction | None = None,
         add_requests: AddRequestsFunction | None = None,
         get_key_value_store: GetKeyValueStoreFromRequestHandlerFunction | None = None,

src/crawlee/_utils/recoverable_state.py

@@ -192,7 +192,7 @@ async def persist_state(self, event_data: EventPersistStateData | None = None) -
             await self._key_value_store.set_value(
                 self._persist_state_key,
                 self._state.model_dump(mode='json', by_alias=True),
-                'application/json',
+                content_type='application/json',
             )
         else:
             self._log.debug('Persistence is not enabled - not doing anything')

src/crawlee/browsers/_browser_controller.py

@@ -72,6 +72,7 @@ def browser_type(self) -> BrowserType:
     @abstractmethod
     async def new_page(
         self,
+        *,
         browser_new_context_options: Mapping[str, Any] | None = None,
         proxy_info: ProxyInfo | None = None,
     ) -> Page:

src/crawlee/browsers/_playwright_browser.py

@@ -40,6 +40,7 @@ def __init__(
         self,
         browser_type: BrowserType,
         user_data_dir: str | Path | None,
+        *,
         browser_launch_options: dict[str, Any],
     ) -> None:
         self._browser_type = browser_type

src/crawlee/browsers/_playwright_browser_controller.py

@@ -157,6 +157,7 @@ def browser_type(self) -> BrowserType:
     @override
     async def new_page(
         self,
+        *,
         browser_new_context_options: Mapping[str, Any] | None = None,
         proxy_info: ProxyInfo | None = None,
     ) -> Page:

src/crawlee/browsers/_playwright_browser_plugin.py

@@ -190,7 +190,9 @@ async def new_browser(self) -> PlaywrightBrowserController:
         if self._use_incognito_pages:
             browser: Browser | PlaywrightPersistentBrowser = await browser_type.launch(**self._browser_launch_options)
         else:
-            browser = PlaywrightPersistentBrowser(browser_type, self._user_data_dir, self._browser_launch_options)
+            browser = PlaywrightPersistentBrowser(
+                browser_type, self._user_data_dir, browser_launch_options=self._browser_launch_options
+            )
 
         return PlaywrightBrowserController(
             browser,