docs: document sequence arguments to any_ and all_

<!-- Provide a general summary of your proposed changes in the Title field above -->

### Description
<!-- Describe your changes in detail -->

Document that Python sequences passed to `any_()` or `all_()` should be
wrapped in `literal()` to form a SQL expression, and clarify that PostgreSQL
array-parameter adaptation depends on the DBAPI.

Fixes: #13357
### Checklist
<!-- go over following points. check them with an `x` if they do apply, (they turn into clickable checkboxes once the PR is submitted, so no need to do everything at once)

-->

This pull request is:

- [x] A documentation / typographical / small typing error fix
	- Good to go, no issue or tests are needed
- [ ] A short code fix
	- please include the issue number, and create an issue if none exists, which
	  must include a complete example of the issue.  one line code fixes without an
	  issue and demonstration will not be accepted.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.   one line code fixes without tests will not be accepted.
- [ ] A new feature implementation
	- please include the issue number, and create an issue if none exists, which must
	  include a complete example of how the feature would look.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.

**Have a nice day!**

Closes: #13456
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/13456
Pull-request-sha: fcc704f0909ca21cd998bd0fc3896d02aa0fe2fd

Change-Id: Iac9c79c8e5b0b4762c6d969ed76038ef2ccf972f

diff --git a/lib/sqlalchemy/sql/_elements_constructors.py b/lib/sqlalchemy/sql/_elements_constructors.py
index 1273d7c23a5da29522658c88762049f4752ad4a4..7da1107d550bd32865efa1d75b2231a9600ea8e3 100644 (file)
--- a/lib/sqlalchemy/sql/_elements_constructors.py
+++ b/lib/sqlalchemy/sql/_elements_constructors.py
@@ -84,6 +84,12 @@ def all_(expr: _ColumnExpressionArgument[_T]) -> CollectionAggregate[bool]:
         # '5 = ALL (SELECT value FROM table)'
         expr = 5 == all_(select(table.c.value))
 
+    When using a Python sequence with PostgreSQL, wrap it with
+    :func:`_sql.literal` to produce a SQL expression.  Whether the sequence
+    can be adapted to an array parameter is DBAPI-specific::
+
+        expr = 5 == all_(literal([1, 2, 3]))
+
     Comparison to NULL may work using ``None``::
 
         None == all_(mytable.c.somearray)
@@ -267,6 +273,12 @@ def any_(expr: _ColumnExpressionArgument[_T]) -> CollectionAggregate[bool]:
         # '5 = ANY (SELECT value FROM table)'
         expr = 5 == any_(select(table.c.value))
 
+    When using a Python sequence with PostgreSQL, wrap it with
+    :func:`_sql.literal` to produce a SQL expression.  Whether the sequence
+    can be adapted to an array parameter is DBAPI-specific::
+
+        expr = 5 == any_(literal([1, 2, 3]))
+
     Comparison to NULL may work using ``None`` or :func:`_sql.null`::
 
         None == any_(mytable.c.somearray)