Merge pull request #126 from elliot-100/docstring-improvements

docstring-improvements

spond_classes/__init__.py

@@ -1,5 +1,6 @@
-"""Explicitly import all classes and functions into the package namespace."""
+"""Main module."""
 
+# Explicitly import all classes and functions into the package namespace.
 # `import x as x` pattern used here for explicit re-export for Mypy
 
 from .event import Event as Event

spond_classes/event.py

@@ -1,68 +1,40 @@
-"""Module for `Event` class and nested `Responses` class."""
+"""Module containing `Event` class and nested `Responses` class."""
 
 from datetime import datetime
 
 from pydantic import BaseModel, Field
 
 
 class Responses(BaseModel):
-    """Represents the responses to an `Event`.
-
-    Attributes
-    ----------
-    accepted_uids: list[str]
-        `acceptedIds` in API.
-
-    declined_uids: list[str]
-        `declinedIds` in API.
-
-    unanswered_uids: list[str]
-        `unansweredIds` in API.
-
-    unconfirmed_uids: list[str]
-        `unconfirmedIds` in API.
-
-    waiting_list_uids: list[str]
-        `waitinglistIds` in API.
-    """
+    """Represents the responses to an `Event`."""
 
     # Lists which always exist in API data, but may be empty
     accepted_uids: list[str] = Field(alias="acceptedIds")
+    """`acceptedIds` in API."""
     declined_uids: list[str] = Field(alias="declinedIds")
+    """`declinedIds` in API."""
     unanswered_uids: list[str] = Field(alias="unansweredIds")
+    """`unansweredIds` in API."""
     waiting_list_uids: list[str] = Field(alias="waitinglistIds")
+    """`waitinglistIds` in API."""
     unconfirmed_uids: list[str] = Field(alias="unconfirmedIds")
+    """`unconfirmedIds` in API."""
 
 
 class Event(BaseModel):
     """Represents an event in the Spond system.
 
-    `Event`s are retrieved from the `events` API endpoint.
-
-    Attributes
-    ----------
-    uid : str
-        id of the `Event`.
-
-        `id` in API, but that's a reserved term and the `spond` package uses `uid`.
-
-    heading : str
-        Heading/name of the `Event`.
-
-        `heading` in API.
-
-    responses : `Responses`
-
-    start_time : datetime
-        Datetime at which the `Event` starts.
-
-        Derived from `startTimestamp` in API.
+    Events data is retrieved from the `events` API endpoint.
     """
 
     uid: str = Field(alias="id")
+    """`id` in API, but that's a reserved term in Python and the Spond package
+    uses `uid`."""
     heading: str
     responses: Responses
     start_time: datetime = Field(alias="startTimestamp")
+    """Datetime at which the `Event` starts.
+    Derived from `startTimestamp` in API."""
 
     def __str__(self) -> str:
         """Return simple human-readable description.

spond_classes/group.py

@@ -1,4 +1,4 @@
-"""Module for `Group` class."""
+"""Module containing `Group` class."""
 
 from pydantic import BaseModel, Field
 
@@ -10,46 +10,24 @@
 class Group(BaseModel):
     """Represents a group in the Spond system.
 
-    `Group`s are retrieved from the `groups` API endpoint.
+    Groups data is retrieved from the `groups` API endpoint.
 
     A `Group` has zero, one or more nested `Member`s; zero, one or more nested `Role`s;
     zero, one or more nested `Subgroup`s.
-
-    Attributes
-    ----------
-    uid : str
-        id of the `Group`.
-
-        `id` in API, but that's a reserved term and the `spond` package uses `uid`.
-
-    members : list[Member]
-        `Member`s belonging to the `Group`.
-
-        Derived from `members` in API.
-
-    name : str
-        Name of the `Group`.
-
-        `name` in API.
-
-    roles : list[Role]
-        `Role`s belonging to the `Group`.
-
-        Derived from `roles` in API.
-
-    subgroups : list[Subgroup]
-        `Subgroup`s belonging to the `Group`.
-
-        Derived from `subGroups` in API.
     """
 
     uid: str = Field(alias="id")
+    """`id` in API, but that's a reserved term in Python and the Spond package
+    uses `uid`."""
     name: str
 
     # Lists which always exist in API data, but may be empty
     members: list[Member]
+    """`Member`s belonging to the `Group`. Derived from `members` in API."""
     roles: list[Role]
+    """`Role`s belonging to the `Group`. Derived from `roles` in API."""
     subgroups: list[Subgroup] = Field(alias="subGroups")
+    """`Subgroup`s belonging to the `Group`. Derived from `subGroups` in API."""
 
     def __str__(self) -> str:
         """Return simple human-readable description.
@@ -63,7 +41,7 @@ def member_by_id(self, member_uid: str) -> Member:
 
         Parameters
         ----------
-        member_uid : str
+        member_uid
             ID to look up.
 
         Returns
@@ -72,7 +50,7 @@ def member_by_id(self, member_uid: str) -> Member:
 
         Raises
         ------
-        `LookupError`
+        `LookupError` :
             If `uid` is not found.
         """
         for member in self.members:
@@ -86,7 +64,7 @@ def role_by_id(self, role_uid: str) -> Role:
 
         Parameters
         ----------
-        role_uid : str
+        role_uid
             ID to look up.
 
         Returns
@@ -95,7 +73,7 @@ def role_by_id(self, role_uid: str) -> Role:
 
         Raises
         ------
-        `LookupError`
+        `LookupError` :
             If `uid` is not found.
         """
         for role in self.roles:
@@ -109,7 +87,7 @@ def subgroup_by_id(self, subgroup_uid: str) -> Subgroup:
 
         Parameters
         ----------
-        subgroup_uid : str
+        subgroup_uid
             ID to look up.
 
         Returns
@@ -118,7 +96,7 @@ def subgroup_by_id(self, subgroup_uid: str) -> Subgroup:
 
         Raises
         ------
-        `LookupError`
+        `LookupError` :
             If `uid` is not found.
         """
         for subgroup in self.subgroups:
@@ -137,11 +115,11 @@ def members_by_subgroup(self, subgroup: Subgroup) -> list[Member]:
 
         Returns
         -------
-        `list[Member]`
+        list[`Member`]
 
         Raises
         ------
-        `TypeError`
+        `TypeError` :
             If `subgroup` is not a `Subgroup` instance.
         """
         if not isinstance(subgroup, Subgroup):
@@ -161,11 +139,11 @@ def members_by_role(self, role: Role) -> list[Member]:
 
         Returns
         -------
-        `list[Member]`
+        list[`Member`]
 
         Raises
         ------
-        `TypeError`
+        `TypeError` :
             If `role` is not a `Role` instance.
         """
         if not isinstance(role, Role):

spond_classes/member.py

@@ -1,4 +1,4 @@
-"""Module for `Member` class."""
+"""Module containing `Member` class."""
 
 from datetime import datetime
 
@@ -12,52 +12,31 @@ class Member(BaseModel):
 
     A `Member` is an individual's group-specific record, and is nested within a `Group`.
     A `Member` may have a nested `Profile`.
-
-    Attributes
-    ----------
-    uid : str
-        id of the `Member`.
-
-        `id` in API, but that's a reserved term and the `spond` package uses `uid`.
-
-    created_time : datetime
-        Derived from `createdTime` in API.
-
-    email : str
-        `email` in API.
-
-    first_name : str
-        `firstName` in API.
-
-    last_name : str
-        `lastName` in API.
-
-    phone_number : str | None
-        `phoneNumber` in API.
-
-    profile : Profile | None
-        Derived from `profile` in API.
-
-    role_uids : list[str] | None
-        `roles` in API, but aliased here to avoid confusion with `Role`s.
-
-    subgroup_uids : list[str]
-        `subGroups` in API, but aliased here to avoid confusion with `Subgroup`s.
     """
 
     uid: str = Field(alias="id")
+    """`id` in API, but that's a reserved term in Python and the Spond package
+    uses `uid`."""
     created_time: datetime = Field(alias="createdTime")
+    """Derived from `createdTime` in API."""
     first_name: str = Field(alias="firstName")
+    """`firstName` in API."""
     last_name: str = Field(alias="lastName")
+    """`lastName` in API."""
 
     # Lists which always exist in API data, but may be empty
     subgroup_uids: list[str] = Field(alias="subGroups")
+    """`subGroups` in API, but aliased here to avoid confusion with
+    `Subgroup` instances."""
 
     # Optional in API data
     email: str | None = Field(default=None)
     phone_number: str | None = Field(alias="phoneNumber", default=None)
+    """`phoneNumber` in API."""
     profile: Profile | None = None  # Availability may depend on permissions
+    """Derived from `profile` in API."""
     role_uids: list[str] | None = Field(alias="roles", default=None)
+    """`roles` in API, but aliased here to avoid confusion with `Role` instances."""
 
     def __str__(self) -> str:
         """Return simple human-readable description.

spond_classes/profile.py

@@ -1,4 +1,4 @@
-"""Module for `Profile` class."""
+"""Module containing `Profile` class."""
 
 from pydantic import BaseModel, Field
 
@@ -7,16 +7,11 @@ class Profile(BaseModel):
     """Represents a profile in the Spond system.
 
     A `Profile` is nested within a `Member`.
-
-    Attributes
-    ----------
-    uid : str
-        id of the `Profile`.
-
-        `id` in API, but that's a reserved term and the `spond` package uses `uid`.
     """
 
     uid: str = Field(alias="id")
+    """`id` in API, but that's a reserved term in Python and the Spond package
+    uses `uid`."""
 
     def __str__(self) -> str:
         """Return simple human-readable description."""

spond_classes/role.py

@@ -1,4 +1,4 @@
-"""Module for `Role` class."""
+"""Module containing `Role` class."""
 
 from pydantic import BaseModel, Field
 
@@ -8,22 +8,12 @@ class Role(BaseModel):
 
     A `Role` is nested within a `Group`.
 
-    Use `Group.members_by_role()` to get `Member`s.
-
-    Attributes
-    ----------
-    uid : str
-        id of the `Role`.
-
-        `id` in API, but that's a reserved term and the `spond` package uses `uid`.
-
-    name : str
-        Name of the `Role`.
-
-        `name` in API.
+    Use `Group.members_by_role()` to get `Member` instances.
     """
 
     uid: str = Field(alias="id")
+    """`id` in API, but that's a reserved term in Python and the Spond package
+    uses `uid`."""
     name: str
 
     def __str__(self) -> str:

spond_classes/subgroup.py

@@ -1,4 +1,4 @@
-"""Module for `Subgroup` class."""
+"""Module containing `Subgroup` class."""
 
 from pydantic import BaseModel, Field
 
@@ -8,23 +8,12 @@ class Subgroup(BaseModel):
 
     A `Subgroup` is nested within a `Group`.
 
-    Use `Group.members_by_subgroup()` to get
-    `Member`s.
-
-    Attributes
-    ----------
-    uid : str
-        id of the `Subgroup`.
-
-        `id` in API, but that's a reserved term and the `spond` package uses `uid`.
-
-    name : str
-        Name of the `Subgroup`.
-
-        `name` in API.
+    Use `Group.members_by_subgroup()` to get `Member` instances.
     """
 
     uid: str = Field(alias="id")
+    """`id` in API, but that's a reserved term in Python and the Spond package
+    uses `uid`."""
     name: str
 
     def __str__(self) -> str: