Defines custom models for verticals (#65)

Closes #60 

This PR defines the models for the different verticals we support in
`pardner` at the moment. I opted to use
[Pydantic](https://docs.pydantic.dev/latest/) to define these models
since it's flexible, leverages a lot of typing concepts already built
into Python, and is easy to serialize/deserialize.

As a reminder, we don't have plans to store any data in `pardner`,
that's the responsibility of the user of the library.

Next up:
- #61
- #62
- #63
- #64

Author: aborem

pyproject.toml

@@ -14,7 +14,11 @@ classifiers = [
 ]
 license = "Apache-2.0"
 license-files = ["LICENSE"]
-dependencies = ["oauthlib>=3.3.1", "requests-oauthlib>=2.0.0"]
+dependencies = [
+    "oauthlib>=3.3.1",
+    "pydantic>=2.11.7",
+    "requests-oauthlib>=2.0.0",
+]
 
 [dependency-groups]
 dev = [

src/pardner/verticals/__init__.py

@@ -1 +1,13 @@
+from pardner.verticals import sub_verticals as sub_verticals
+from pardner.verticals.base import BaseVertical as BaseVertical
 from pardner.verticals.base import Vertical as Vertical
+from pardner.verticals.blocked_user import BlockedUserVertical as BlockedUserVertical
+from pardner.verticals.chat_bot import ChatBotVertical as ChatBotVertical
+from pardner.verticals.conversation import ConversationVertical as ConversationVertical
+from pardner.verticals.message import MessageVertical as MessageVertical
+from pardner.verticals.physical_activity import (
+    PhysicalActivityVertical as PhysicalActivityVertical,
+)
+from pardner.verticals.social_posting import (
+    SocialPostingVertical as SocialPostingVertical,
+)

src/pardner/verticals/base.py

@@ -1,6 +1,10 @@
+from abc import ABC
+from datetime import datetime
 from enum import StrEnum
 from typing import Optional
 
+from pydantic import AnyHttpUrl, BaseModel, Field
+
 
 class Vertical(StrEnum):
     """
@@ -23,3 +27,21 @@ def __new__(cls, singular: str, plural: Optional[str] = None) -> 'Vertical':
         vertical_obj._value_ = singular
         vertical_obj.plural = plural if plural else f'{singular}s'
         return vertical_obj
+
+
+class BaseVertical(BaseModel, ABC):
+    """
+    Base class for all verticals, except sub-verticals. Represents the verticals, or
+    categories of data, that are supported by this library. Not all verticals are
+    supported by every transfer service.
+    """
+
+    id: str
+    creator_user_id: str
+    service: str = Field(
+        description='The name of the service the data was pulled from.'
+    )
+    vertical_name: str = Field(description='The name of the vertical, in snake case.')
+
+    created_at: datetime | None = None
+    url: AnyHttpUrl | None = None

src/pardner/verticals/blocked_user.py

@@ -0,0 +1,8 @@
+from pardner.verticals import BaseVertical
+
+
+class BlockedUserVertical(BaseVertical):
+    """An instance of a user blocked by ``creator_user_id``."""
+
+    vertical_name: str = 'blocked_user'
+    blocked_user_id: str

src/pardner/verticals/chat_bot.py

@@ -0,0 +1,7 @@
+from pardner.verticals import BaseVertical
+
+
+class ChatBotVertical(BaseVertical):
+    """An instance of a chatbot created by ``creator_user_id``."""
+
+    vertical_name: str = 'chat_bot'

src/pardner/verticals/conversation.py

@@ -0,0 +1,24 @@
+from pydantic import Field
+
+from pardner.verticals import BaseVertical
+from pardner.verticals.sub_verticals import AssociatedMediaSubVertical
+
+
+class ConversationVertical(BaseVertical):
+    """
+    The metadata related to a conversation where messages are exchanged between one
+    or more people.
+    """
+
+    vertical_name: str = 'conversation'
+    is_group_conversation: bool
+
+    abstract: str | None = Field(
+        description='A short summary, description, or bio.', default=None
+    )
+    associated_media: list[AssociatedMediaSubVertical] = []
+    is_private: bool | None = None
+    member_user_ids: list[str] = []
+    members_count: int | None = None
+    messages_count: int | None = None
+    title: str | None = None

src/pardner/verticals/message.py

@@ -0,0 +1,15 @@
+from pardner.verticals import BaseVertical, ConversationVertical
+from pardner.verticals.sub_verticals import AssociatedMediaSubVertical
+
+
+class MessageVertical(BaseVertical):
+    """
+    A communication sent by ``creator_user_id`` and one or more
+    recipients. This is related to a :class:`ConversationVertical`.
+    """
+
+    vertical_name: str = 'message'
+    parent_conversation: ConversationVertical
+
+    associated_media: list[AssociatedMediaSubVertical] = []
+    text: str | None = None

src/pardner/verticals/physical_activity.py

@@ -0,0 +1,29 @@
+from datetime import datetime
+
+from pydantic import Field
+
+from pardner.verticals.social_posting import SocialPostingVertical
+
+
+class PhysicalActivityVertical(SocialPostingVertical):
+    """
+    A social posting that contains information related to a physical activity, such
+    as running, swimming, or walking.
+    """
+
+    vertical_name: str = 'physical_activity'
+
+    activity_type: str | None = Field(
+        description='The type of physical activity, such as a hike.', default=None
+    )
+    distance: float | None = Field(description='In meters.', default=None)
+    elevation_high: float | None = Field(description='In meters.', default=None)
+    elevation_low: float | None = Field(description='In meters.', default=None)
+    kilocalories: float | None = None
+    max_speed: float | None = Field(description='In meters per second.', default=None)
+    start_datetime: datetime | None = None
+    start_latitude: float | None = None
+    start_longitude: float | None = None
+    end_datetime: datetime | None = None
+    end_latitude: float | None = None
+    end_longitude: float | None = None

src/pardner/verticals/social_posting.py

@@ -0,0 +1,25 @@
+from typing import Literal
+
+from pydantic import Field
+
+from pardner.verticals import BaseVertical
+from pardner.verticals.sub_verticals import AssociatedMediaSubVertical
+
+
+class SocialPostingVertical(BaseVertical):
+    """
+    A post on social media.
+    """
+
+    vertical_name: str = 'social_posting'
+
+    abstract: str | None = Field(
+        description='A short summary, description, or bio.', default=None
+    )
+    associated_media: list[AssociatedMediaSubVertical] = []
+    interaction_count: int | None = None
+    keywords: list[str] = []
+    shared_content: list['SocialPostingVertical'] = []
+    status: Literal['private', 'public', 'draft', 'restricted'] | None = None
+    text: str | None = None
+    title: str | None = None

src/pardner/verticals/sub_verticals/__init__.py

@@ -0,0 +1,4 @@
+from pardner.verticals.sub_verticals.associated_media import (
+    AssociatedMediaSubVertical as AssociatedMediaSubVertical,
+)
+from pardner.verticals.sub_verticals.base import BaseSubVertical as BaseSubVertical