Improve the pool API and default behavior, and change param precedence (#207)

Author: Gallaecio

CHANGES.rst

@@ -1,6 +1,41 @@
 Changes
 =======
 
+Unreleased
+----------
+
+* The precedence of session param settings, request metadata keys and session
+  config override methods has changed.
+
+  Before, priority from higher to lower was:
+
+  #.  :meth:`~scrapy_zyte_api.SessionConfig.params`
+
+  #.  :meth:`~scrapy_zyte_api.SessionConfig.location`
+
+  #.  :reqmeta:`zyte_api_session_location`
+
+  #.  :setting:`ZYTE_API_SESSION_LOCATION`
+
+  #.  :reqmeta:`zyte_api_session_params`
+
+  #.  :setting:`ZYTE_API_SESSION_PARAMS`
+
+  Now, it is:
+
+  #.  :reqmeta:`zyte_api_session_params`
+
+  #.  :reqmeta:`zyte_api_session_location`
+
+  #.  :setting:`ZYTE_API_SESSION_PARAMS`
+
+  #.  :setting:`ZYTE_API_SESSION_LOCATION`
+
+  #.  :meth:`~scrapy_zyte_api.SessionConfig.location`
+
+  #.  :meth:`~scrapy_zyte_api.SessionConfig.params`
+
+
 0.20.0 (2024-06-26)
 -------------------
 

docs/reference/meta.rst

@@ -98,6 +98,8 @@ Default: :setting:`ZYTE_API_SESSION_ENABLED`
 Whether to use :ref:`scrapy-zyte-api session management <session>` for the
 request (``True``) or not (``False``).
 
+.. seealso:: :meth:`scrapy_zyte_api.SessionConfig.enabled`
+
 
 .. reqmeta:: zyte_api_session_location
 
@@ -106,13 +108,19 @@ zyte_api_session_location
 
 Default: ``{}``
 
-Address for ``setLocation``-based session initialization. See
-:setting:`ZYTE_API_SESSION_LOCATION` for details.
+See :ref:`session-init` for general information about location configuration
+and parameter precedence.
+
+Example:
 
-This request metadata key, if not empty, takes precedence over the
-:setting:`ZYTE_API_SESSION_LOCATION` setting, the
-:setting:`ZYTE_API_SESSION_PARAMS` setting, and the
-:reqmeta:`zyte_api_session_location` request metadata key.
+.. code-block:: python
+
+    Request(
+        "https://example.com",
+        meta={
+            "zyte_api_session_location": {"postalCode": "10001"},
+        },
+    )
 
 
 .. reqmeta:: zyte_api_session_params
@@ -122,10 +130,18 @@ zyte_api_session_params
 
 Default: ``{}``
 
-Parameters to use for session initialization. See
-:setting:`ZYTE_API_SESSION_PARAMS` for details.
+See :ref:`session-init` for general information about defining session
+initialization parameters and parameter precedence.
+
+
+.. reqmeta:: zyte_api_session_pool
+
+zyte_api_session_pool
+=====================
+
+Default: ``""``
+
+Determines the ID of the session pool to assign to the request, overriding the
+:ref:`default pool assignment logic <session-pools>`.
 
-This request metadata key, if not empty, takes precedence over the
-:setting:`ZYTE_API_SESSION_PARAMS` setting, but it can be overridden
-by the :setting:`ZYTE_API_SESSION_LOCATION` setting or the
-:reqmeta:`zyte_api_session_location` request metadata key.
+.. seealso:: :meth:`scrapy_zyte_api.SessionConfig.pool`

docs/reference/settings.rst

@@ -354,30 +354,16 @@ ZYTE_API_SESSION_LOCATION
 
 Default: ``{}``
 
-If defined, sessions are initialized using the ``setLocation``
-:http:`action <request:actions>`, and the value of this setting must be the
-target address :class:`dict`. For example:
+See :ref:`session-init` for general information about location configuration
+and parameter precedence.
+
+Example:
 
 .. code-block:: python
     :caption: settings.py
 
     ZYTE_API_SESSION_LOCATION = {"postalCode": "10001"}
 
-If the :setting:`ZYTE_API_SESSION_PARAMS` setting or the
-:reqmeta:`zyte_api_session_params` request metadata key set a ``"url"``, it
-will be used for session initialization as well. Otherwise, the URL of the
-request for which the session is being initialized will be used instead.
-
-This setting, if not empty, takes precedence over the
-:setting:`ZYTE_API_SESSION_PARAMS` setting and the
-:reqmeta:`zyte_api_session_params` request metadata key, but it can be
-overridden by the :reqmeta:`zyte_api_session_location` request metadata key.
-
-To disable the :setting:`ZYTE_API_SESSION_LOCATION` setting on a specific
-request, e.g. to use the :setting:`ZYTE_API_SESSION_PARAMS` setting or the
-:reqmeta:`zyte_api_session_params` request metadata key instead, set
-the :reqmeta:`zyte_api_session_location` request metadata key to ``{}``.
-
 
 .. setting:: ZYTE_API_SESSION_MAX_BAD_INITS
 
@@ -430,20 +416,10 @@ to work even after an unsuccessful response. See :ref:`optimize-sessions`.
 ZYTE_API_SESSION_PARAMS
 =======================
 
-Default: ``{"browserHtml": True}``
-
-Parameters to use for session initialization.
-
-It works similarly to :http:`request:sessionContextParams` from
-:ref:`server-managed sessions <zyte-api-session-contexts>`, but it supports
-arbitrary Zyte API parameters instead of a specific subset.
-
-If it does not define a ``"url"``, the URL of the request for which the session
-is being initialized will be used.
+Default: ``{}``
 
-This setting can be overridden by the :setting:`ZYTE_API_SESSION_LOCATION`
-setting, the :reqmeta:`zyte_api_session_location` request metadata key, or the
-:reqmeta:`zyte_api_session_params` request metadata key.
+See :ref:`session-init` for general information about defining session
+initialization parameters and parameter precedence.
 
 Example: