feat: add legacy exception compatibility aliases

This PR adds backward compatibility for users importing exceptions from
`replicate.exceptions` instead of directly from the `replicate` module.

The new `replicate/exceptions.py` module re-exports all exception classes
from the internal `_exceptions` module, allowing both import patterns to work:
- `from replicate import ModelError` (existing)
- `from replicate.exceptions import ModelError` (legacy compatibility)

This ensures backward compatibility with code that uses the legacy import
pattern shown in documentation examples.

Author: zeke

requirements-dev.lock

@@ -78,9 +78,10 @@ mypy-extensions==1.0.0
 nodeenv==1.8.0
     # via pyright
 nox==2023.4.22
-packaging==23.2
+packaging==25.0
     # via nox
     # via pytest
+    # via replicate
 platformdirs==3.11.0
     # via virtualenv
 pluggy==1.5.0

requirements.lock

@@ -52,6 +52,8 @@ idna==3.4
 multidict==6.4.4
     # via aiohttp
     # via yarl
+packaging==25.0
+    # via replicate
 propcache==0.3.1
     # via aiohttp
     # via yarl

src/replicate/exceptions.py

@@ -0,0 +1,47 @@
+"""
+Legacy compatibility module for exception imports.
+
+This module provides backward compatibility for users importing exceptions
+from `replicate.exceptions` instead of directly from `replicate`.
+
+All exceptions are also available directly from the `replicate` module.
+"""
+
+from __future__ import annotations
+
+# Import all exceptions from the internal module
+from ._exceptions import (
+    APIError,
+    ModelError,
+    ConflictError,
+    NotFoundError,
+    APIStatusError,
+    RateLimitError,
+    ReplicateError,
+    APITimeoutError,
+    BadRequestError,
+    APIConnectionError,
+    AuthenticationError,
+    InternalServerError,
+    PermissionDeniedError,
+    UnprocessableEntityError,
+    APIResponseValidationError,
+)
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "InternalServerError",
+    "ModelError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ReplicateError",
+    "UnprocessableEntityError",
+]

tests/test_api_token_compatibility.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import os
 import pytest
 
 from replicate import Replicate, AsyncReplicate, ReplicateError
@@ -86,4 +85,4 @@ def test_bearer_token_overrides_env(self, monkeypatch: pytest.MonkeyPatch) -> No
         """Test that explicit bearer_token overrides environment variable."""
         monkeypatch.setenv("REPLICATE_API_TOKEN", "env_token")
         client = Replicate(bearer_token="explicit_token")
-        assert client.bearer_token == "explicit_token"
+        assert client.bearer_token == "explicit_token"

tests/test_legacy_exceptions.py

@@ -0,0 +1,80 @@
+"""Tests for legacy exception import compatibility."""
+
+from __future__ import annotations
+
+import pytest
+
+
+def test_legacy_exception_imports():
+    """Test that exceptions can be imported from replicate.exceptions."""
+    # Test importing individual exceptions from replicate.exceptions
+    from replicate.exceptions import (
+        APIConnectionError,
+        APIError,
+        APIResponseValidationError,
+        APIStatusError,
+        APITimeoutError,
+        AuthenticationError,
+        BadRequestError,
+        ConflictError,
+        InternalServerError,
+        ModelError,
+        NotFoundError,
+        PermissionDeniedError,
+        RateLimitError,
+        ReplicateError,
+        UnprocessableEntityError,
+    )
+
+    # Test that imported exceptions are the same as the ones from replicate
+    import replicate
+
+    assert ModelError is replicate._exceptions.ModelError
+    assert APIError is replicate.APIError
+    assert ReplicateError is replicate.ReplicateError
+    assert BadRequestError is replicate.BadRequestError
+    assert AuthenticationError is replicate.AuthenticationError
+    assert NotFoundError is replicate.NotFoundError
+    assert RateLimitError is replicate.RateLimitError
+    assert InternalServerError is replicate.InternalServerError
+    assert APIConnectionError is replicate.APIConnectionError
+    assert APITimeoutError is replicate.APITimeoutError
+
+
+def test_readme_example_import():
+    """Test that the import pattern shown in README works correctly."""
+    # This is the exact import pattern shown in the README
+    import replicate
+    from replicate.exceptions import ModelError
+
+    # Verify ModelError is the correct class
+    assert ModelError is replicate._exceptions.ModelError
+
+
+def test_exception_module_all_exports():
+    """Test that replicate.exceptions.__all__ contains all expected exceptions."""
+    import replicate.exceptions
+
+    expected_exceptions = [
+        "APIConnectionError",
+        "APIError",
+        "APIResponseValidationError",
+        "APIStatusError",
+        "APITimeoutError",
+        "AuthenticationError",
+        "BadRequestError",
+        "ConflictError",
+        "InternalServerError",
+        "ModelError",
+        "NotFoundError",
+        "PermissionDeniedError",
+        "RateLimitError",
+        "ReplicateError",
+        "UnprocessableEntityError",
+    ]
+
+    assert set(replicate.exceptions.__all__) == set(expected_exceptions)
+
+    # Also verify they can all be accessed
+    for exc_name in expected_exceptions:
+        assert hasattr(replicate.exceptions, exc_name)