diff --git a/spond_classes/__init__.py b/spond_classes/__init__.py index 42044b9..5f01922 100644 --- a/spond_classes/__init__.py +++ b/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 diff --git a/spond_classes/event.py b/spond_classes/event.py index 2f57cf3..18d9832 100644 --- a/spond_classes/event.py +++ b/spond_classes/event.py @@ -1,4 +1,4 @@ -"""Module for `Event` class and nested `Responses` class.""" +"""Module containing `Event` class and nested `Responses` class.""" from datetime import datetime @@ -6,63 +6,35 @@ 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. diff --git a/spond_classes/group.py b/spond_classes/group.py index 4eb3e50..01fd700 100644 --- a/spond_classes/group.py +++ b/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): diff --git a/spond_classes/member.py b/spond_classes/member.py index 1d38cd7..4ed5af3 100644 --- a/spond_classes/member.py +++ b/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. diff --git a/spond_classes/profile.py b/spond_classes/profile.py index 3affe80..33deaad 100644 --- a/spond_classes/profile.py +++ b/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.""" diff --git a/spond_classes/role.py b/spond_classes/role.py index fe10dd3..1845317 100644 --- a/spond_classes/role.py +++ b/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: diff --git a/spond_classes/subgroup.py b/spond_classes/subgroup.py index f3afba5..af58593 100644 --- a/spond_classes/subgroup.py +++ b/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: