feat: support API versioning

Author: jacobbednarz

src/cloudflare/_base_client.py

@@ -333,6 +333,7 @@ class BaseClient(Generic[_HttpxClientT, _DefaultStreamT]):
     _client: _HttpxClientT
     _version: str
     _base_url: URL
+    _api_version: str
     max_retries: int
     timeout: Union[float, Timeout, None]
     _strict_response_validation: bool
@@ -344,6 +345,7 @@ def __init__(
         *,
         version: str,
         base_url: str | URL,
+        api_version: str,
         _strict_response_validation: bool,
         max_retries: int = DEFAULT_MAX_RETRIES,
         timeout: float | Timeout | None = DEFAULT_TIMEOUT,
@@ -352,6 +354,7 @@ def __init__(
     ) -> None:
         self._version = version
         self._base_url = self._enforce_trailing_slash(URL(base_url))
+        self.api_version = api_version
         self.max_retries = max_retries
         self.timeout = timeout
         self._custom_headers = custom_headers or {}
@@ -425,6 +428,8 @@ def _build_headers(self, options: FinalRequestOptions, *, retries_taken: int = 0
             if timeout is not None:
                 headers["x-stainless-read-timeout"] = str(timeout)
 
+        headers["api-version"] = self.api_version
+
         return headers
 
     def _prepare_url(self, url: str) -> URL:
@@ -486,7 +491,7 @@ def _build_request(
                     raise TypeError(
                         f"Expected query input to be a dictionary for multipart requests but got {type(json_data)} instead."
                     )
-                    
+
                 if options.multipart_syntax == 'json':
                     json_data = cast("Mapping[str, object]", json_data)
                     if is_mapping_t(files):
@@ -820,6 +825,7 @@ def __init__(
         *,
         version: str,
         base_url: str | URL,
+        api_version: str,
         max_retries: int = DEFAULT_MAX_RETRIES,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
         http_client: httpx.Client | None = None,
@@ -850,6 +856,7 @@ def __init__(
             # cast to a valid type because mypy doesn't understand our type narrowing
             timeout=cast(Timeout, timeout),
             base_url=base_url,
+            api_version=api_version,
             max_retries=max_retries,
             custom_query=custom_query,
             custom_headers=custom_headers,
@@ -1350,6 +1357,7 @@ def __init__(
         *,
         version: str,
         base_url: str | URL,
+        api_version: str,
         _strict_response_validation: bool,
         max_retries: int = DEFAULT_MAX_RETRIES,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
@@ -1378,6 +1386,7 @@ def __init__(
         super().__init__(
             version=version,
             base_url=base_url,
+            api_version=api_version,
             # cast to a valid type because mypy doesn't understand our type narrowing
             timeout=cast(Timeout, timeout),
             max_retries=max_retries,

src/cloudflare/_client.py

@@ -4,6 +4,7 @@
 
 import os
 from typing import TYPE_CHECKING, Any, Union, Mapping
+from datetime import datetime
 from typing_extensions import Self, override
 
 import httpx
@@ -280,6 +281,7 @@ def __init__(
         api_email: str | None = None,
         user_service_key: str | None = None,
         base_url: str | httpx.URL | None = None,
+        api_version: str | None = None,
         timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
         max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Mapping[str, str] | None = None,
@@ -327,9 +329,13 @@ def __init__(
         if base_url is None:
             base_url = f"https://api.cloudflare.com/client/v4"
 
+        if api_version is None:
+            api_version = datetime.today().strftime('%Y-%m-%d')
+
         super().__init__(
             version=__version__,
             base_url=base_url,
+            api_version=api_version,
             max_retries=max_retries,
             timeout=timeout,
             http_client=http_client,
@@ -1001,6 +1007,7 @@ def copy(
         api_email: str | None = None,
         user_service_key: str | None = None,
         base_url: str | httpx.URL | None = None,
+        api_version: str | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
         http_client: httpx.Client | None = None,
         max_retries: int | NotGiven = NOT_GIVEN,
@@ -1038,6 +1045,7 @@ def copy(
             api_email=api_email or self.api_email,
             user_service_key=user_service_key or self.user_service_key,
             base_url=base_url or self.base_url,
+            api_version=api_version or self.api_version,
             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,
@@ -1099,6 +1107,7 @@ def __init__(
         api_email: str | None = None,
         user_service_key: str | None = None,
         base_url: str | httpx.URL | None = None,
+        api_version: str | None = None,
         timeout: Union[float, Timeout, None, NotGiven] = NOT_GIVEN,
         max_retries: int = DEFAULT_MAX_RETRIES,
         default_headers: Mapping[str, str] | None = None,
@@ -1146,9 +1155,13 @@ def __init__(
         if base_url is None:
             base_url = f"https://api.cloudflare.com/client/v4"
 
+        if api_version is None:
+            api_version = datetime.today().strftime('%Y-%m-%d')
+
         super().__init__(
             version=__version__,
             base_url=base_url,
+            api_version=api_version,
             max_retries=max_retries,
             timeout=timeout,
             http_client=http_client,