fix: add+update docstrings for API models and requests

- Fixes docstring test to properly identify and correct docstrings for API models
- Fixes missing docstrings in API models

Author: tazlin

horde_sdk/ai_horde_api/apimodels/documents.py

@@ -19,6 +19,14 @@ class DocumentFormat(StrEnum):
 
 
 class HordeDocument(HordeResponseBaseModel):
+    """Represents the data returned from the following endpoints and http status codes:
+        - /v2/documents/terms | AIHordeGetTermsRequest [GET] -> 200
+        - /v2/documents/sponsors | AIHordeGetSponsorsRequest [GET] -> 200
+        - /v2/documents/privacy | AIHordeGetPrivacyPolicyRequest [GET] -> 200
+
+    v2 API Model: `HordeDocument`
+    """
+
     html: str | None = None
     """The HTML content of the document, if requested."""
     markdown: str | None = None
@@ -50,6 +58,8 @@ def validate_format(cls, value: DocumentFormat | str) -> DocumentFormat | str:
 
 
 class AIHordeGetPrivacyPolicyRequest(BaseAIHordeRequest, AIHordeDocumentRequestMixin):
+    """Represents a GET request to the /v2/documents/privacy endpoint."""
+
     @override
     @classmethod
     def get_api_model_name(cls) -> str | None:
@@ -72,6 +82,8 @@ def get_default_success_response_type(cls) -> type[HordeDocument]:
 
 
 class AIHordeGetSponsorsRequest(BaseAIHordeRequest, AIHordeDocumentRequestMixin):
+    """Represents a GET request to the /v2/documents/sponsors endpoint."""
+
     @override
     @classmethod
     def get_api_model_name(cls) -> str | None:
@@ -94,6 +106,8 @@ def get_default_success_response_type(cls) -> type[HordeDocument]:
 
 
 class AIHordeGetTermsRequest(BaseAIHordeRequest, AIHordeDocumentRequestMixin):
+    """Represents a GET request to the /v2/documents/terms endpoint."""
+
     @override
     @classmethod
     def get_api_model_name(cls) -> str | None:

horde_sdk/ai_horde_api/apimodels/generate/text/async_.py

@@ -208,6 +208,11 @@ class ModelGenerationInputKobold(ModelPayloadRootKobold):
 
 
 class TextGenerateAsyncDryRunResponse(HordeResponseBaseModel):
+    """Represents the data returned from the /v2/generate/text/async endpoint with http status code 200.
+
+    v2 API Model: `_ANONYMOUS_MODEL`
+    """
+
     kudos: float
     """The expected kudos consumption for this request."""
 
@@ -223,7 +228,7 @@ class TextGenerateAsyncRequest(
     APIKeyAllowedInRequestMixin,
     RequestUsesWorkerMixin,
 ):
-    """Represents the data needed to make a request to the `/v2/generate/async` endpoint.
+    """Represents a POST request to the /v2/generate/text/async endpoint.
 
     v2 API Model: `GenerationInputKobold`
     """

horde_sdk/ai_horde_api/apimodels/users.py

@@ -22,7 +22,7 @@
 class ContributionsDetails(HordeAPIObjectBaseModel):
     """How many images and megapixelsteps this user has generated.
 
-    v2 API Model: ContributionsDetails
+    v2 API Model: `ContributionsDetails`
     """
 
     fulfillments: int | None = Field(
@@ -43,7 +43,7 @@ def get_api_model_name(cls) -> str | None:
 class UserKudosDetails(HordeAPIObjectBaseModel):
     """The details of the kudos this user has accumulated, used, sent and received.
 
-    v2 API Model: UserKudosDetails
+    v2 API Model: `UserKudosDetails`
     """
 
     accumulated: float | None = Field(0)
@@ -79,7 +79,7 @@ def get_api_model_name(cls) -> str | None:
 class MonthlyKudos(HordeAPIObjectBaseModel):
     """The details of the monthly kudos this user receives.
 
-    v2 API Model: MonthlyKudos
+    v2 API Model: `MonthlyKudos`
     """
 
     amount: int | None = Field(default=None)
@@ -97,7 +97,7 @@ def get_api_model_name(cls) -> str | None:
 class UserThingRecords(HordeAPIObjectBaseModel):
     """How many images, texts, megapixelsteps and tokens this user has generated or requested.
 
-    v2 API Model: UserThingRecords
+    v2 API Model: `UserThingRecords`
     """
 
     megapixelsteps: float | None = Field(0)
@@ -115,7 +115,7 @@ def get_api_model_name(cls) -> str | None:
 class UserAmountRecords(HordeAPIObjectBaseModel):
     """How many images, texts, megapixelsteps and tokens this user has generated or requested.
 
-    v2 API Model: UserAmountRecords
+    v2 API Model: `UserAmountRecords`
     """
 
     image: int | None = Field(0)
@@ -136,7 +136,7 @@ def get_api_model_name(cls) -> str | None:
 class UserRecords(HordeAPIObjectBaseModel):
     """How many images, texts, megapixelsteps, tokens and styles this user has generated, requested or has had used.
 
-    v2 API Model: UserRecords
+    v2 API Model: `UserRecords`
     """
 
     contribution: UserThingRecords | None = None
@@ -159,7 +159,7 @@ def get_api_model_name(cls) -> str | None:
 class UsageDetails(HordeAPIObjectBaseModel):
     """How many images and megapixelsteps this user has requested.
 
-    v2 API Model: UsageDetails
+    v2 API Model: `UsageDetails`
     """
 
     megapixelsteps: float | None = Field(default=None)
@@ -179,7 +179,7 @@ def get_api_model_name(cls) -> str | None:
 class ActiveGenerations(HordeAPIObjectBaseModel):
     """A list of generations that are currently active for this user.
 
-    v2 API Model: ActiveGenerations
+    v2 API Model: `ActiveGenerations`
     """
 
     """A list of generations that are currently active for this user."""
@@ -380,7 +380,9 @@ def get_api_model_name(cls) -> str | None:
 class ListUsersDetailsResponse(HordeResponseRootModel[list[UserDetailsResponse]]):
     """The response for a list of user details.
 
-    v2 API Model: _ANONYMOUS_MODEL
+    Represents the data returned from the /v2/users endpoint with http status code 200.
+
+    v2 API Model: `_ANONYMOUS_MODEL`
     """
 
     root: list[UserDetailsResponse]
@@ -393,7 +395,10 @@ def get_api_model_name(cls) -> str:
 
 
 class ListUsersDetailsRequest(BaseAIHordeRequest):
-    """Represents a request to list all users."""
+    """Represents a request to list all users.
+
+    Represents a GET request to the /v2/users endpoint.
+    """
 
     page: int
     """The page number to request. There are up to 25 users per page."""
@@ -427,7 +432,9 @@ def get_query_fields(cls) -> list[str]:
         return ["page", "sort"]
 
 
-class SingleUserDetailsRequest(BaseAIHordeRequest, RequestSpecifiesUserIDMixin):
+class SingleUserDetailsRequest(BaseAIHordeRequest, MessageSpecifiesUserIDMixin):
+    """Represents a GET request to the /v2/users/{user_id} endpoint."""
+
     @override
     @classmethod
     def get_api_model_name(cls) -> None:
@@ -571,6 +578,11 @@ class ModifyUserReply(_ModifyUserBase):
 
 
 class ModifyUserResponse(HordeResponseBaseModel, ModifyUserReply):
+    """Represents the data returned from the /v2/users/{user_id} endpoint with http status code 200.
+
+    v2 API Model: `ModifyUser`
+    """
+
     @override
     @classmethod
     def get_api_model_name(cls) -> str:
@@ -583,6 +595,11 @@ class ModifyUserRequest(
     ModifyUser,
     APIKeyAllowedInRequestMixin,
 ):
+    """Represents a PUT request to the /v2/users/{user_id} endpoint.
+
+    v2 API Model: `ModifyUserInput`
+    """
+
     @override
     @classmethod
     def get_api_model_name(cls) -> str:

horde_sdk/meta.py

@@ -514,17 +514,24 @@ def process_response(response_request_infos: list[FoundResponseInfo]) -> None:
     def process_other(class_type: type[HordeAPIObject]) -> None:
         api_model_name = class_type.get_api_model_name()
 
-        expected_other_docstring = v2_api_model_template.format(api_model=api_model_name)
+        expected_suffix = v2_api_model_template.format(api_model=api_model_name)
 
         if not class_type.__doc__:
             return
 
         original_other_docstring = class_type.__doc__.rstrip()
         original_other_docstring = original_other_docstring.replace("\n\n    ", "\n\n")
 
-        expected_other_docstring = expected_other_docstring.replace("\n\n    ", "\n\n")
-        if not original_other_docstring.endswith(expected_other_docstring):
-            non_conforming_other[class_type] = (class_type.__doc__, expected_other_docstring)
+        expected_suffix_normalized = expected_suffix.replace("\n\n    ", "\n\n")
+        if not original_other_docstring.endswith(expected_suffix_normalized):
+            # Extract the description portion (everything before any "v2 API Model:" line)
+            # to construct the full expected docstring
+            description_part = original_other_docstring
+            if "\n\nv2 API Model:" in original_other_docstring:
+                description_part = original_other_docstring.split("\n\nv2 API Model:")[0]
+
+            full_expected_docstring = description_part + expected_suffix_normalized
+            non_conforming_other[class_type] = (original_other_docstring, full_expected_docstring)
 
     _sorted_all_classes = sorted(all_classes, key=lambda x: x.__name__)
     _sorted_all_classes.reverse()