chore: update naming

Author: tilyupo

README.md

@@ -81,8 +81,8 @@ client = Replane(
     # Default context applied to all get() calls
     context={"environment": "production"},
 
-    # Fallback values used if server is unavailable during init
-    fallbacks={
+    # Default values used if server is unavailable during init
+    defaults={
         "rate-limit": 100,
         "feature-enabled": False,
     },

docs/source/configuration.md

@@ -16,7 +16,7 @@ replane = Replane(
 
     # Optional
     context={"environment": "production"},
-    fallbacks={"rate-limit": 100, "feature-enabled": False},
+    defaults={"rate-limit": 100, "feature-enabled": False},
     required=["rate-limit", "feature-enabled"],
     request_timeout_ms=2000,
     initialization_timeout_ms=5000,
@@ -29,6 +29,7 @@ replane = Replane(
 ### Required Options
 
 #### `base_url`
+
 - **Type:** `str`
 - **Required:** Yes
 
@@ -40,6 +41,7 @@ base_url="http://localhost:3000"  # Local development
 ```
 
 #### `sdk_key`
+
 - **Type:** `str`
 - **Required:** Yes
 
@@ -53,6 +55,7 @@ sdk_key="rp_test_xyz789..."  # Testing/staging
 ### Optional Options
 
 #### `context`
+
 - **Type:** `dict[str, str | int | float | bool | None]`
 - **Default:** `{}`
 
@@ -76,28 +79,31 @@ value = replane.get("config-name", context={"user_id": "123"})
 # Effective context: {"environment": "production", "region": "us-east", "user_id": "123"}
 ```
 
-#### `fallbacks`
+#### `defaults`
+
 - **Type:** `dict[str, Any]`
 - **Default:** `{}`
 
-Fallback values used when configs can't be loaded from the server. This is useful for resilience - your application can still function with sensible defaults if the Replane server is unavailable.
+Default values used when configs can't be loaded from the server. This is useful for resilience - your application can still function with sensible defaults if the Replane server is unavailable.
 
 ```python
 replane = Replane(
     ...,
-    fallbacks={
+    defaults={
         "rate-limit": 100,
         "feature-enabled": False,
         "max-connections": 10,
     },
 )
 ```
 
-Fallbacks are used in two scenarios:
+Defaults are used in two scenarios:
+
 1. During initialization if a config isn't returned by the server
 2. If `get()` is called before initialization completes
 
 #### `required`
+
 - **Type:** `list[str]`
 - **Default:** `[]`
 
@@ -114,6 +120,7 @@ replane = Replane(
 This is useful for catching configuration errors early rather than at runtime.
 
 #### `request_timeout_ms`
+
 - **Type:** `int`
 - **Default:** `2000` (2 seconds)
 
@@ -127,6 +134,7 @@ replane = Replane(
 ```
 
 #### `initialization_timeout_ms`
+
 - **Type:** `int`
 - **Default:** `5000` (5 seconds)
 
@@ -142,6 +150,7 @@ replane = Replane(
 If initialization times out, a `TimeoutError` is raised.
 
 #### `retry_delay_ms`
+
 - **Type:** `int`
 - **Default:** `200` (0.2 seconds)
 
@@ -155,6 +164,7 @@ replane = Replane(
 ```
 
 #### `inactivity_timeout_ms`
+
 - **Type:** `int`
 - **Default:** `30000` (30 seconds)
 
@@ -168,6 +178,7 @@ replane = Replane(
 ```
 
 #### `debug`
+
 - **Type:** `bool`
 - **Default:** `False`
 
@@ -181,6 +192,7 @@ replane = Replane(
 ```
 
 When enabled, you'll see logs for:
+
 - Client initialization parameters
 - SSE connection attempts and status
 - Each config loaded from the server
@@ -190,6 +202,7 @@ When enabled, you'll see logs for:
 - Client close operations
 
 Example output:
+
 ```
 2024-01-15 10:30:00 [DEBUG] replane: Initializing Replane: base_url=https://replane.example.com, ...
 2024-01-15 10:30:00 [DEBUG] replane: connect() called, wait=True

docs/source/errors.md

@@ -19,19 +19,19 @@ ReplaneError (base class)
 
 Each `ReplaneError` has a `code` attribute from the `ErrorCode` enum:
 
-| Code | Description |
-|------|-------------|
-| `not_found` | Config doesn't exist |
-| `timeout` | Operation timed out |
-| `network_error` | Network request failed |
-| `auth_error` | Authentication failed (invalid SDK key) |
-| `forbidden` | Access denied |
-| `server_error` | Server returned 5xx error |
-| `client_error` | Client error (4xx) |
-| `closed` | Client has been closed |
-| `not_initialized` | Client not yet initialized |
-| `missing_dependency` | Required dependency not installed |
-| `unknown` | Unknown error |
+| Code                 | Description                             |
+| -------------------- | --------------------------------------- |
+| `not_found`          | Config doesn't exist                    |
+| `timeout`            | Operation timed out                     |
+| `network_error`      | Network request failed                  |
+| `auth_error`         | Authentication failed (invalid SDK key) |
+| `forbidden`          | Access denied                           |
+| `server_error`       | Server returned 5xx error               |
+| `client_error`       | Client error (4xx)                      |
+| `closed`             | Client has been closed                  |
+| `not_initialized`    | Client not yet initialized              |
+| `missing_dependency` | Required dependency not installed       |
+| `unknown`            | Unknown error                           |
 
 ## Handling Errors
 
@@ -103,18 +103,19 @@ except ConfigNotFoundError as e:
 ```
 
 **Attributes:**
+
 - `config_name: str` - Name of the missing config
 
-**Prevention:** Use `default` parameter or `fallbacks` option:
+**Prevention:** Use `default` parameter or `defaults` option:
 
 ```python
 # With default
 value = replane.get("config", default="fallback")
 
-# With fallbacks during init
+# With defaults during init
 replane = Replane(
     ...,
-    fallbacks={"config": "fallback"},
+    defaults={"config": "fallback"},
 )
 ```
 
@@ -132,6 +133,7 @@ except TimeoutError as e:
 ```
 
 **Attributes:**
+
 - `timeout_ms: int | None` - Timeout value in milliseconds
 
 **Prevention:** Increase timeout values:
@@ -158,6 +160,7 @@ except AuthenticationError:
 ```
 
 **Common causes:**
+
 - Invalid SDK key
 - SDK key for wrong environment
 - Revoked SDK key
@@ -178,6 +181,7 @@ except NetworkError as e:
 ```
 
 **Common causes:**
+
 - Server unreachable
 - DNS resolution failed
 - Connection refused
@@ -232,6 +236,7 @@ except MissingDependencyError as e:
 ```
 
 **Attributes:**
+
 - `dependency: str` - Name of the missing package
 - `feature: str` - Feature that requires the dependency
 
@@ -251,7 +256,7 @@ except ReplaneError as e:
 ## Best Practices
 
 1. **Catch specific exceptions first**, then fall back to `ReplaneError`
-2. **Use fallbacks** for resilience against missing configs
+2. **Use defaults** for resilience against missing configs
 3. **Log errors** with their codes for debugging
 4. **Don't catch and ignore** - at minimum, log the error
 5. **Use `default` parameter** instead of catching `ConfigNotFoundError` when appropriate

docs/source/frameworks.md

@@ -366,4 +366,4 @@ if __name__ == "__main__":
 2. **Close on shutdown** - Always close the client when your application shuts down
 3. **Use context managers** - When possible, use `with`/`async with` for automatic cleanup
 4. **Handle errors** - Wrap initialization in try/except for graceful degradation
-5. **Use fallbacks** - Configure fallback values for resilience
+5. **Use defaults** - Configure default values for resilience

replane/_async.py

@@ -84,7 +84,7 @@ def __init__(
         sdk_key: str,
         *,
         context: dict[str, ContextValue] | None = None,
-        fallbacks: dict[str, Any] | None = None,
+        defaults: dict[str, Any] | None = None,
         required: list[str] | None = None,
         request_timeout_ms: int = 2000,
         initialization_timeout_ms: int = 5000,
@@ -99,7 +99,7 @@ def __init__(
             base_url: Base URL of the Replane server.
             sdk_key: SDK key for authentication.
             context: Default context for override evaluation.
-            fallbacks: Fallback values for configs if not loaded from server.
+            defaults: Default values for configs if not loaded or abs from server.
             required: List of config names that must be present on init.
             request_timeout_ms: Timeout for HTTP requests in milliseconds.
             initialization_timeout_ms: Timeout for initial connection.
@@ -130,15 +130,15 @@ def __init__(
             )
             if context:
                 logger.debug("Default context: %s", context)
-            if fallbacks:
-                logger.debug("Fallback configs: %s", list(fallbacks.keys()))
+            if defaults:
+                logger.debug("Default configs: %s", list(defaults.keys()))
             if required:
                 logger.debug("Required configs: %s", required)
 
         self._base_url = base_url.rstrip("/")
         self._sdk_key = sdk_key
         self._context = context or {}
-        self._fallbacks = fallbacks or {}
+        self._defaults = defaults or {}
         self._required = set(required or [])
         self._request_timeout = request_timeout_ms / 1000.0
         self._init_timeout = initialization_timeout_ms / 1000.0
@@ -150,8 +150,8 @@ def __init__(
         self._configs: dict[str, Config] = {}
         self._lock = asyncio.Lock()
 
-        # Initialize fallbacks
-        for name, value in self._fallbacks.items():
+        # Initialize defaults
+        for name, value in self._defaults.items():
             self._configs[name] = Config(name=name, value=value)
 
         # Subscription callbacks

replane/_sync.py

@@ -83,7 +83,7 @@ def __init__(
         sdk_key: str,
         *,
         context: dict[str, ContextValue] | None = None,
-        fallbacks: dict[str, Any] | None = None,
+        defaults: dict[str, Any] | None = None,
         required: list[str] | None = None,
         request_timeout_ms: int = 2000,
         initialization_timeout_ms: int = 5000,
@@ -98,7 +98,7 @@ def __init__(
             base_url: Base URL of the Replane server.
             sdk_key: SDK key for authentication.
             context: Default context for override evaluation.
-            fallbacks: Fallback values for configs if not loaded from server.
+            defaults: Default values for configs if not loaded from server.
             required: List of config names that must be present on init.
             request_timeout_ms: Timeout for HTTP requests in milliseconds.
             initialization_timeout_ms: Timeout for initial connection.
@@ -123,14 +123,14 @@ def __init__(
             )
             if context:
                 logger.debug("Default context: %s", context)
-            if fallbacks:
-                logger.debug("Fallback configs: %s", list(fallbacks.keys()))
+            if defaults:
+                logger.debug("Default configs: %s", list(defaults.keys()))
             if required:
                 logger.debug("Required configs: %s", required)
         self._base_url = base_url.rstrip("/")
         self._sdk_key = sdk_key
         self._context = context or {}
-        self._fallbacks = fallbacks or {}
+        self._defaults = defaults or {}
         self._required = set(required or [])
         self._request_timeout = request_timeout_ms / 1000.0
         self._init_timeout = initialization_timeout_ms / 1000.0
@@ -142,8 +142,8 @@ def __init__(
         self._configs: dict[str, Config] = {}
         self._lock = threading.RLock()
 
-        # Initialize fallbacks
-        for name, value in self._fallbacks.items():
+        # Initialize defaults
+        for name, value in self._defaults.items():
             self._configs[name] = Config(name=name, value=value)
 
         # Subscription callbacks

tests/test_async_client.py

@@ -182,7 +182,7 @@ async def test_fallback_configs(self, mock_server: MockSSEServer):
         async with AsyncReplane(
             base_url=mock_server.url,
             sdk_key="rp_test_key",
-            fallbacks={"fallback-config": "fallback-value"},
+            defaults={"fallback-config": "fallback-value"},
         ) as client:
             assert client.get("from-server") == "server"
             assert client.get("fallback-config") == "fallback-value"
@@ -194,7 +194,7 @@ async def test_server_overrides_fallback(self, mock_server: MockSSEServer):
         async with AsyncReplane(
             base_url=mock_server.url,
             sdk_key="rp_test_key",
-            fallbacks={"config": "from-fallback"},
+            defaults={"config": "from-fallback"},
         ) as client:
             assert client.get("config") == "from-server"
 

tests/test_sync_client.py

@@ -182,7 +182,7 @@ def test_fallback_configs(self, mock_server: MockSSEServer):
         with Replane(
             base_url=mock_server.url,
             sdk_key="rp_test_key",
-            fallbacks={"fallback-config": "fallback-value"},
+            defaults={"fallback-config": "fallback-value"},
         ) as client:
             assert client.get("from-server") == "server"
             assert client.get("fallback-config") == "fallback-value"
@@ -194,7 +194,7 @@ def test_server_overrides_fallback(self, mock_server: MockSSEServer):
         with Replane(
             base_url=mock_server.url,
             sdk_key="rp_test_key",
-            fallbacks={"config": "from-fallback"},
+            defaults={"config": "from-fallback"},
         ) as client:
             assert client.get("config") == "from-server"