chore: move api related files to models/api

Author: Stewitch

bot_sdk/__init__.py

@@ -8,6 +8,8 @@
 	CommandSpec,
 	InvalidArgumentsError,
 	UnknownCommandError,
+	OptionValidator,
+    Validator,
 )
 from .runner import BotRunner
 from .logging import setup_logging
@@ -57,4 +59,6 @@
 	"User",
     "GetUserGroupsRequest",
 	"GetUserGroupsResponse",
+    "Validator",
+	"OptionValidator",
 ]

bot_sdk/commands.py

@@ -31,13 +31,74 @@ async def send_reply(self, message: Any, content: str) -> Any:
         ...
 
 
+class Validator(Protocol):
+    """Callable validator that may coerce or reject a value."""
+
+    def __call__(self, value: Any) -> Any:
+        ...
+
+    def help_hint(self) -> Optional[str]:  # optional, but recommended
+        ...
+
+
+class OptionValidator:
+    """Ensure a value is one of the allowed options (useful for enums).
+
+    By default the match is case-sensitive. Set ``case_insensitive`` to allow
+    case-insensitive string comparison while still returning the original
+    value.
+    """
+
+    def __init__(self, options: Iterable[Any], *, case_insensitive: bool = False) -> None:
+        opts = list(options)
+        if not opts:
+            raise ValueError("options must not be empty")
+        self.options = opts
+        self.case_insensitive = case_insensitive
+        if case_insensitive:
+            self._normalized_map = {self._normalize(opt): opt for opt in opts}
+        else:
+            self._allowed = set(opts)
+
+    def __call__(self, value: Any) -> Any:
+        if self.case_insensitive and isinstance(value, str):
+            normalized = self._normalize(value)
+            if normalized in self._normalized_map:
+                return self._normalized_map[normalized]
+            self._raise_error(value)
+
+        if not self.case_insensitive:
+            if value in self._allowed:
+                return value
+            self._raise_error(value)
+
+        # If case-insensitive but the value is not a string, fall back to direct membership.
+        if value in self.options:
+            return value
+        self._raise_error(value)
+
+    def _raise_error(self, value: Any) -> None:
+        choices = ", ".join(str(opt) for opt in self.options)
+        raise ValueError(f"Value must be one of: {choices} (got {value})")
+
+    @staticmethod
+    def _normalize(value: Any) -> str:
+        return str(value).lower()
+
+    def help_hint(self) -> str:
+        choices = ", ".join(str(opt) for opt in self.options)
+        suffix = " (case-insensitive)" if self.case_insensitive else ""
+        return f"options: {choices}{suffix}"
+
+
 @dataclass
 class CommandArgument:
     name: str
     type: type = str
     required: bool = True
     description: str = ""
     multiple: bool = False  # capture the remainder of args
+    validator: Optional[Validator] = None
 
 
 @dataclass
@@ -190,9 +251,17 @@ def _parse_args(self, args_tokens: List[str], spec: CommandSpec) -> Dict[str, An
     def _convert_value(self, value: str, arg_spec: CommandArgument) -> ArgType:
         target = arg_spec.type
         try:
+            converted: ArgType
             if target is bool:
-                return self._to_bool(value)
-            return target(value)
+                converted = self._to_bool(value)
+            else:
+                converted = target(value)
+
+            if arg_spec.validator is not None:
+                return arg_spec.validator(converted)
+            return converted
+        except InvalidArgumentsError:
+            raise
         except Exception as exc:  # pragma: no cover - simple conversion guard
             raise InvalidArgumentsError(arg_spec.name, f"Invalid value for {arg_spec.name}: {value}") from exc
 
@@ -263,11 +332,27 @@ def _format_spec_detail(self, spec: CommandSpec) -> str:
                 requirement = "required" if arg.required else "optional"
                 multi = " (multiple)" if arg.multiple else ""
                 desc = f" - {arg.name}: {requirement}{multi}"
+                validator_hint = self._format_validator_hint(arg.validator)
                 if arg.description:
                     desc += f" — {arg.description}"
+                if validator_hint:
+                    desc += f" [{validator_hint}]"
                 lines.append(desc)
         return "\n".join(lines)
 
+    @staticmethod
+    def _format_validator_hint(validator: Optional[Validator]) -> str:
+        if validator is None:
+            return ""
+        hint_fn = getattr(validator, "help_hint", None)
+        if callable(hint_fn):
+            try:
+                hint = hint_fn()
+                return str(hint) if hint else ""
+            except Exception:  # pragma: no cover - help rendering should not break help
+                return ""
+        return f"validated by {validator.__class__.__name__}"
+
 
 __all__ = [
     "CommandParser",
@@ -277,4 +362,6 @@ def _format_spec_detail(self, spec: CommandSpec) -> str:
     "CommandError",
     "UnknownCommandError",
     "InvalidArgumentsError",
+    "Validator",
+    "OptionValidator",
 ]

bot_sdk/models/__init__.py

@@ -1,47 +1,12 @@
-from .request import (
-    StreamMessageRequest,
-    PrivateMessageRequest,
-    UpdatePresenceRequest,
-    GetUserGroupsRequest,
-)
-from .response import (
-    RegisterResponse,
-    EventsResponse,
-    SendMessageResponse,
-    UserProfileResponse,
-    SubscriptionsResponse,
-    ChannelResponse,
-    GetUserGroupsResponse,
-)
-from .types import (
-    Message,
-    Event,
-    PrivateRecipient,
-    ProfileFieldValue,
-    User,
-    Channel,
-    UserGroup,
-    GroupSettingValue,
-)
+"""Model package.
 
-__all__ = [
-    "StreamMessageRequest",
-    "PrivateMessageRequest",
-    "RegisterResponse",
-    "EventsResponse",
-    "SendMessageResponse",
-    "UserProfileResponse",
-    "ProfileFieldValue",
-    "User",
-    "SubscriptionsResponse",
-    "ChannelResponse",
-    "Channel",
-    "Message",
-    "Event",
-    "PrivateRecipient",
-    "UpdatePresenceRequest",
-    "GetUserGroupsRequest",
-    "GetUserGroupsResponse",
-    "UserGroup",
-    "GroupSettingValue",
-]
+api/ contains Zulip API-facing models.
+data/ holds SDK-side generic data models; bot-specific models live in bot dirs.
+"""
+
+from .api import *  # noqa: F401,F403
+from .data import *  # noqa: F401,F403
+from .api import __all__ as _api_all
+from .data import __all__ as _data_all
+
+__all__ = list(_api_all) + list(_data_all)

bot_sdk/models/api/__init__.py

@@ -0,0 +1,47 @@
+from .request import (
+    StreamMessageRequest,
+    PrivateMessageRequest,
+    UpdatePresenceRequest,
+    GetUserGroupsRequest,
+)
+from .response import (
+    RegisterResponse,
+    EventsResponse,
+    SendMessageResponse,
+    UserProfileResponse,
+    SubscriptionsResponse,
+    ChannelResponse,
+    GetUserGroupsResponse,
+)
+from .types import (
+    Message,
+    Event,
+    PrivateRecipient,
+    ProfileFieldValue,
+    User,
+    Channel,
+    UserGroup,
+    GroupSettingValue,
+)
+
+__all__ = [
+    "StreamMessageRequest",
+    "PrivateMessageRequest",
+    "RegisterResponse",
+    "EventsResponse",
+    "SendMessageResponse",
+    "UserProfileResponse",
+    "ProfileFieldValue",
+    "User",
+    "SubscriptionsResponse",
+    "ChannelResponse",
+    "Channel",
+    "Message",
+    "Event",
+    "PrivateRecipient",
+    "UpdatePresenceRequest",
+    "GetUserGroupsRequest",
+    "GetUserGroupsResponse",
+    "UserGroup",
+    "GroupSettingValue",
+]

bot_sdk/models/request.py bot_sdk/models/api/request.pybot_sdk/models/request.py renamed to bot_sdk/models/api/request.py

@@ -39,4 +39,4 @@ class GetUserGroupsRequest(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-__all__ = ["StreamMessageRequest", "PrivateMessageRequest", "UpdatePresenceRequest", "GetUserGroupsRequest"]
+__all__ = ["StreamMessageRequest", "PrivateMessageRequest", "UpdatePresenceRequest", "GetUserGroupsRequest"]

bot_sdk/models/response.py bot_sdk/models/api/response.pybot_sdk/models/response.py renamed to bot_sdk/models/api/response.py

@@ -122,4 +122,4 @@ class UserGroup(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-__all__ = ["Message", "Event", "PrivateRecipient", "ProfileFieldValue", "User", "Channel", "GroupSettingValue", "UserGroup"]
+__all__ = ["Message", "Event", "PrivateRecipient", "ProfileFieldValue", "User", "Channel", "GroupSettingValue", "UserGroup"]

bot_sdk/models/types.py bot_sdk/models/api/types.pybot_sdk/models/types.py renamed to bot_sdk/models/api/types.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pydantic import BaseModel, ConfigDict
+
+
+class DataModel(BaseModel):
+    """Base Pydantic model for SDK-side data structures.
+
+    - Disallows unknown fields by default
+    - Ready to be extended by bot developers for their own data schemas
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Timestamped(DataModel):
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+__all__ = ["DataModel", "Timestamped"]