Align max_running error wording and document the >= 1 constraint

Match the '>= 1, got N' phrasing used by OnlineEvaluator (pydantic#6267), note
the constraint in the ConcurrencyLimit and ConcurrencyLimiter docstrings,
and drop the stale 'before a run can hang' test wording.

Author: adtyavrdhn

pydantic_ai_slim/pydantic_ai/concurrency.py

@@ -25,7 +25,7 @@
 def _validate_max_running(max_running: int) -> None:
     if max_running < 1:
         raise UserError(
-            f'max_running must be a positive integer, got {max_running}. Use None for no concurrency limiting.'
+            f'max_running must be >= 1, got {max_running}. Use None for no concurrency limiting.'
         )
 
 
@@ -76,7 +76,7 @@ class ConcurrencyLimit:
     """Configuration for concurrency limiting with optional backpressure.
 
     Args:
-        max_running: Maximum number of concurrent operations allowed.
+        max_running: Maximum number of concurrent operations allowed. Must be >= 1.
         max_queued: Maximum number of operations waiting in the queue.
             If None, the queue is unlimited. If exceeded, raises `ConcurrencyLimitExceeded`.
     """
@@ -107,11 +107,14 @@ def __init__(
         """Initialize the ConcurrencyLimiter.
 
         Args:
-            max_running: Maximum number of concurrent operations.
+            max_running: Maximum number of concurrent operations. Must be >= 1.
             max_queued: Maximum queue depth before raising ConcurrencyLimitExceeded.
             name: Optional name for this limiter, used for observability when sharing
                 a limiter across multiple models or agents.
             tracer: OpenTelemetry tracer for span creation.
+
+        Raises:
+            UserError: If `max_running` is less than 1.
         """
         _validate_max_running(max_running)
         self._limiter = anyio.CapacityLimiter(max_running)

tests/test_concurrency.py

@@ -70,13 +70,13 @@ async def test_nowait_acquisition(self):
     @pytest.mark.parametrize('max_running', [0, -1, -5])
     async def test_invalid_max_running(self, max_running: int):
         """Test that invalid concurrency limits are rejected before creating the limiter."""
-        with pytest.raises(UserError, match=f'max_running must be a positive integer, got {max_running}'):
+        with pytest.raises(UserError, match=f'max_running must be >= 1, got {max_running}'):
             ConcurrencyLimiter(max_running=max_running)
 
     @pytest.mark.parametrize('max_running', [0, -1, -5])
     async def test_invalid_concurrency_limit_config(self, max_running: int):
         """Test that invalid concurrency limit config values fail eagerly."""
-        with pytest.raises(UserError, match=f'max_running must be a positive integer, got {max_running}'):
+        with pytest.raises(UserError, match=f'max_running must be >= 1, got {max_running}'):
             ConcurrencyLimit(max_running=max_running)
 
     async def test_waiting_count_tracking(self):
@@ -208,12 +208,12 @@ async def test_from_limiter_config(self):
 
     async def test_from_invalid_limit(self):
         """Test that invalid normalized concurrency limits fail eagerly."""
-        with pytest.raises(UserError, match='max_running must be a positive integer, got 0'):
+        with pytest.raises(UserError, match='max_running must be >= 1, got 0'):
             ConcurrencyLimiter.from_limit(0)
 
     async def test_normalize_to_limiter_rejects_invalid_limit(self):
         """Test that invalid normalized concurrency limits fail before use."""
-        with pytest.raises(UserError, match='max_running must be a positive integer, got 0'):
+        with pytest.raises(UserError, match='max_running must be >= 1, got 0'):
             normalize_to_limiter(0)
 
     async def test_none_still_means_no_limit(self):
@@ -335,8 +335,8 @@ async def test_agent_with_limiter_concurrency(self):
 
     @pytest.mark.parametrize('max_running', [0, -1])
     async def test_agent_invalid_int_concurrency_limit(self, max_running: int):
-        """Test that invalid agent concurrency limits fail before a run can hang."""
-        with pytest.raises(UserError, match=f'max_running must be a positive integer, got {max_running}'):
+        """Test that invalid agent concurrency limits fail eagerly at construction."""
+        with pytest.raises(UserError, match=f'max_running must be >= 1, got {max_running}'):
             Agent(TestModel(), max_concurrency=max_running)