feat(api): support environments

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 2
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/landingai%2Fade-f08049b74d593128128837d1e62b642bf68ee132184fddadc45d19fbc6d9f263.yml
 openapi_spec_hash: 1cf6912d5249120cb222db3890587aab
-config_hash: 113449d0f864a31adaa7683357b11b72
+config_hash: ca433b766050897382afeb5c04a1bdee

README.md

@@ -30,11 +30,11 @@ from ade import Ade
 
 client = Ade(
     apikey=os.environ.get("ADE_API_KEY"),  # This is the default and can be omitted
+    # defaults to "production".
+    environment="eu-production",
 )
 
-response = client.ade.parse(
-    document=b"/path/to/file",
-)
+response = client.ade.parse()
 print(response.chunks)
 ```
 
@@ -54,13 +54,13 @@ from ade import AsyncAde
 
 client = AsyncAde(
     apikey=os.environ.get("ADE_API_KEY"),  # This is the default and can be omitted
+    # defaults to "production".
+    environment="eu-production",
 )
 
 
 async def main() -> None:
-    response = await client.ade.parse(
-        document=b"/path/to/file",
-    )
+    response = await client.ade.parse()
     print(response.chunks)
 
 
@@ -93,9 +93,7 @@ async def main() -> None:
         apikey="My Apikey",
         http_client=DefaultAioHttpClient(),
     ) as client:
-        response = await client.ade.parse(
-            document=b"/path/to/file",
-        )
+        response = await client.ade.parse()
         print(response.chunks)
 
 

src/ade/__init__.py

@@ -5,7 +5,18 @@
 from . import types
 from ._types import NOT_GIVEN, Omit, NoneType, NotGiven, Transport, ProxiesTypes
 from ._utils import file_from_path
-from ._client import Ade, Client, Stream, Timeout, AsyncAde, Transport, AsyncClient, AsyncStream, RequestOptions
+from ._client import (
+    ENVIRONMENTS,
+    Ade,
+    Client,
+    Stream,
+    Timeout,
+    AsyncAde,
+    Transport,
+    AsyncClient,
+    AsyncStream,
+    RequestOptions,
+)
 from ._models import BaseModel
 from ._version import __title__, __version__
 from ._response import APIResponse as APIResponse, AsyncAPIResponse as AsyncAPIResponse
@@ -61,6 +72,7 @@
     "AsyncStream",
     "Ade",
     "AsyncAde",
+    "ENVIRONMENTS",
     "file_from_path",
     "BaseModel",
     "DEFAULT_TIMEOUT",

src/ade/_client.py

@@ -3,8 +3,8 @@
 from __future__ import annotations
 
 import os
-from typing import Any, Union, Mapping
-from typing_extensions import Self, override
+from typing import Any, Dict, Union, Mapping, cast
+from typing_extensions import Self, Literal, override
 
 import httpx
 
@@ -30,7 +30,22 @@
     AsyncAPIClient,
 )
 
-__all__ = ["Timeout", "Transport", "ProxiesTypes", "RequestOptions", "Ade", "AsyncAde", "Client", "AsyncClient"]
+__all__ = [
+    "ENVIRONMENTS",
+    "Timeout",
+    "Transport",
+    "ProxiesTypes",
+    "RequestOptions",
+    "Ade",
+    "AsyncAde",
+    "Client",
+    "AsyncClient",
+]
+
+ENVIRONMENTS: Dict[str, str] = {
+    "production": "https://api.va.landing.ai",
+    "eu-production": "https://va.eu-west-1.landing.ai",
+}
 
 
 class Ade(SyncAPIClient):
@@ -41,11 +56,14 @@ class Ade(SyncAPIClient):
     # client options
     apikey: str
 
+    _environment: Literal["production", "eu-production"] | NotGiven
+
     def __init__(
         self,
         *,
         apikey: str | None = None,
-        base_url: str | httpx.URL | None = None,
+        environment: Literal["production", "eu-production"] | NotGiven = NOT_GIVEN,
+        base_url: str | httpx.URL | None | NotGiven = NOT_GIVEN,
         timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
         max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Mapping[str, str] | None = None,
@@ -76,10 +94,31 @@ def __init__(
             )
         self.apikey = apikey
 
-        if base_url is None:
-            base_url = os.environ.get("ADE_BASE_URL")
-        if base_url is None:
-            base_url = f"https://api.va.landing.ai"
+        self._environment = environment
+
+        base_url_env = os.environ.get("ADE_BASE_URL")
+        if is_given(base_url) and base_url is not None:
+            # cast required because mypy doesn't understand the type narrowing
+            base_url = cast("str | httpx.URL", base_url)  # pyright: ignore[reportUnnecessaryCast]
+        elif is_given(environment):
+            if base_url_env and base_url is not None:
+                raise ValueError(
+                    "Ambiguous URL; The `ADE_BASE_URL` env var and the `environment` argument are given. If you want to use the environment, you must pass base_url=None",
+                )
+
+            try:
+                base_url = ENVIRONMENTS[environment]
+            except KeyError as exc:
+                raise ValueError(f"Unknown environment: {environment}") from exc
+        elif base_url_env is not None:
+            base_url = base_url_env
+        else:
+            self._environment = environment = "production"
+
+            try:
+                base_url = ENVIRONMENTS[environment]
+            except KeyError as exc:
+                raise ValueError(f"Unknown environment: {environment}") from exc
 
         super().__init__(
             version=__version__,
@@ -120,6 +159,7 @@ def copy(
         self,
         *,
         apikey: str | None = None,
+        environment: Literal["production", "eu-production"] | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
         http_client: httpx.Client | None = None,
@@ -155,6 +195,7 @@ def copy(
         return self.__class__(
             apikey=apikey or self.apikey,
             base_url=base_url or self.base_url,
+            environment=environment or self._environment,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
             http_client=http_client,
             max_retries=max_retries if is_given(max_retries) else self.max_retries,
@@ -209,11 +250,14 @@ class AsyncAde(AsyncAPIClient):
     # client options
     apikey: str
 
+    _environment: Literal["production", "eu-production"] | NotGiven
+
     def __init__(
         self,
         *,
         apikey: str | None = None,
-        base_url: str | httpx.URL | None = None,
+        environment: Literal["production", "eu-production"] | NotGiven = NOT_GIVEN,
+        base_url: str | httpx.URL | None | NotGiven = NOT_GIVEN,
         timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
         max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Mapping[str, str] | None = None,
@@ -244,10 +288,31 @@ def __init__(
             )
         self.apikey = apikey
 
-        if base_url is None:
-            base_url = os.environ.get("ADE_BASE_URL")
-        if base_url is None:
-            base_url = f"https://api.va.landing.ai"
+        self._environment = environment
+
+        base_url_env = os.environ.get("ADE_BASE_URL")
+        if is_given(base_url) and base_url is not None:
+            # cast required because mypy doesn't understand the type narrowing
+            base_url = cast("str | httpx.URL", base_url)  # pyright: ignore[reportUnnecessaryCast]
+        elif is_given(environment):
+            if base_url_env and base_url is not None:
+                raise ValueError(
+                    "Ambiguous URL; The `ADE_BASE_URL` env var and the `environment` argument are given. If you want to use the environment, you must pass base_url=None",
+                )
+
+            try:
+                base_url = ENVIRONMENTS[environment]
+            except KeyError as exc:
+                raise ValueError(f"Unknown environment: {environment}") from exc
+        elif base_url_env is not None:
+            base_url = base_url_env
+        else:
+            self._environment = environment = "production"
+
+            try:
+                base_url = ENVIRONMENTS[environment]
+            except KeyError as exc:
+                raise ValueError(f"Unknown environment: {environment}") from exc
 
         super().__init__(
             version=__version__,
@@ -288,6 +353,7 @@ def copy(
         self,
         *,
         apikey: str | None = None,
+        environment: Literal["production", "eu-production"] | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
         http_client: httpx.AsyncClient | None = None,
@@ -323,6 +389,7 @@ def copy(
         return self.__class__(
             apikey=apikey or self.apikey,
             base_url=base_url or self.base_url,
+            environment=environment or self._environment,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
             http_client=http_client,
             max_retries=max_retries if is_given(max_retries) else self.max_retries,

tests/test_client.py

@@ -550,6 +550,14 @@ def test_base_url_env(self) -> None:
             client = Ade(apikey=apikey, _strict_response_validation=True)
             assert client.base_url == "http://localhost:5000/from/env/"
 
+        # explicit environment arg requires explicitness
+        with update_env(ADE_BASE_URL="http://localhost:5000/from/env"):
+            with pytest.raises(ValueError, match=r"you must pass base_url=None"):
+                Ade(apikey=apikey, _strict_response_validation=True, environment="production")
+
+            client = Ade(base_url=None, apikey=apikey, _strict_response_validation=True, environment="production")
+            assert str(client.base_url).startswith("https://api.va.landing.ai")
+
     @pytest.mark.parametrize(
         "client",
         [
@@ -1347,6 +1355,14 @@ def test_base_url_env(self) -> None:
             client = AsyncAde(apikey=apikey, _strict_response_validation=True)
             assert client.base_url == "http://localhost:5000/from/env/"
 
+        # explicit environment arg requires explicitness
+        with update_env(ADE_BASE_URL="http://localhost:5000/from/env"):
+            with pytest.raises(ValueError, match=r"you must pass base_url=None"):
+                AsyncAde(apikey=apikey, _strict_response_validation=True, environment="production")
+
+            client = AsyncAde(base_url=None, apikey=apikey, _strict_response_validation=True, environment="production")
+            assert str(client.base_url).startswith("https://api.va.landing.ai")
+
     @pytest.mark.parametrize(
         "client",
         [