feat: adds object classes (#104)

* feat: adds LemmyUser object class
* feat: adds lemmy.get_user() which returns a LemmyUser class
* Requires python 3.10+ from now

Author: db0

examples/user_class.py

@@ -0,0 +1,58 @@
+## python examples/user.py db0
+
+import argparse
+import json
+import os
+from pythorhead import Lemmy
+
+arg_parser = argparse.ArgumentParser()
+arg_parser.add_argument("username", action="store")
+arg_parser.add_argument(
+    "-d",
+    "--lemmy_domain",
+    action="store",
+    required=False,
+    type=str,
+    help="the domain in which to look for this user",
+)
+arg_parser.add_argument(
+    "-u",
+    "--lemmy_username",
+    action="store",
+    required=False,
+    type=str,
+    help="Which user to authenticate as",
+)
+arg_parser.add_argument(
+    "-p",
+    "--lemmy_password",
+    action="store",
+    required=False,
+    type=str,
+    help="Which password to authenticate with",
+)
+args = arg_parser.parse_args()
+
+
+lemmy_domain = args.lemmy_domain
+if not lemmy_domain:
+    lemmy_domain = os.getenv("LEMMY_DOMAIN", "lemmy.dbzer0.com")
+if not lemmy_domain:
+    raise Exception("You need to provide a lemmy domain via env var or arg")
+
+lemmy_username = args.lemmy_username
+if not lemmy_username:
+    lemmy_username = os.getenv("LEMMY_USERNAME")
+
+lemmy_password = args.lemmy_password
+if not lemmy_password:
+    lemmy_password = os.getenv("LEMMY_PASSWORD")
+
+lemmy = Lemmy(f"https://{lemmy_domain}", raise_exceptions=True, request_timeout=2)
+if lemmy_username and lemmy_password:
+    login = lemmy.log_in(lemmy_username, lemmy_password)
+user = lemmy.user.get(username=args.username, return_user_object = True)
+if user:
+    print(user.asjson(indent=4))
+else:
+    print("no matching username found")

pyproject.toml

@@ -10,7 +10,7 @@ authors = [
 ]
 version = "v0.26.0"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 license = { file="LICENSE" }
 classifiers = [
     "Programming Language :: Python :: 3",

pythorhead/classes/__init__.py

@@ -0,0 +1,106 @@
+from dataclasses import dataclass, asdict
+from datetime import datetime
+from pythorhead import lemmy
+from pythorhead.types import SortType, ListingType, LanguageType
+from dateutil import parser
+from pythorhead.utils import json_serializer
+
+import json
+
+@dataclass
+class LemmyUser:
+    id: int
+    name: str
+    banned: bool
+    published: datetime
+    actor_id: str
+    local: bool
+    deleted: bool
+    bot_account: bool
+    instance_id: int
+    is_admin: bool
+    display_name: str | None = None
+    bio: str | None = None
+    avatar: str | None = None
+    banner: str | None = None
+    matrix_user_id: str | None = None
+    ban_expires: datetime | None = None
+    updated: datetime | None = None
+    # The owning lemmy instance. We use it to reach the API classes
+    lemmy = None
+    
+    @classmethod
+    def from_dict(cls, person_dict: dict, lemmy) -> 'LemmyUser':
+        # Convert string to datetime for ban_expires if it exists
+        for key in {'ban_expires', 'updates', 'published'}:
+            if key in person_dict and person_dict[key]:
+                person_dict[key] = parser.isoparse(person_dict[key])
+        new_user = cls(**person_dict)
+        new_user.lemmy = lemmy
+        return new_user
+    
+    def refresh(self) -> None:
+        """
+        Update instance attributes from a new dictionary while preserving custom fields.
+        
+        Args:
+            new_data: Dictionary containing updated user data
+        """
+        new_data = self.lemmy.user.get(person_id=self.person_id)
+        # Handle datetime conversion
+        if 'ban_expires' in new_data and new_data['ban_expires']:
+            new_data['ban_expires'] = datetime.fromisoformat(new_data['ban_expires'])
+        
+        for field_name in new_data:
+            setattr(self, field_name, new_data[field_name])
+
+
+    def purge(self) -> None:
+        self.lemmy.user.purge(person_id=self.person_id)
+    
+    def ban(self,
+            ban: bool = True, 
+            expires: datetime | int | None = None, 
+            reason: str | None = None, 
+            remove_data: bool | None = None
+        ) -> None:
+        self.lemmy.user.ban(
+            person_id=self.person_id,
+            ban = ban,
+            expires = expires,
+            reason = reason,
+            remove_data = remove_data,
+        )
+        self.refresh()
+    
+    def update(self):
+        if self.lemmy.user._requestor.logged_in_username != self.name:
+            raise Exception("Cannot update user details for anyone but the currently logged-in user.")
+        self.lemmy.user.save_user_settings(
+            avatar=self.avatar,
+            banner=self.banner,
+            display_name=self.display_name,
+            bio=self.bio,
+            matrix_user_id=self.matrix_user_id,
+            bot_account=self.bot_account,
+        )
+        self.refresh()
+    
+    def set_settings(self, **kwargs):
+        if self.lemmy.user._requestor.logged_in_username != self.name:
+            raise Exception("Cannot update user settings for anyone but the currently logged-in user.")
+        self.lemmy.user.save_user_settings(**kwargs)
+        self.refresh()
+
+    def asdict(self):
+        return asdict(self)
+
+    def asjson(self, indent=4):      
+        selfdict = self.asdict()
+        return json.dumps(selfdict, indent=indent, default=json_serializer)
+    
+    def pm(self, content):
+        self.lemmy.private_message(
+            content=content,
+            recipient_id=self.id,
+        )

pythorhead/classes/user.py

@@ -1,3 +1,4 @@
+from __future__ import annotations
 import logging
 import time
 from typing import Any, Optional
@@ -13,12 +14,22 @@
 from pythorhead.types import FeatureType, ListingType, SortType, SearchType, SearchOption
 from pythorhead.user import User
 from pythorhead.admin import Admin
+from pythorhead.classes.user import LemmyUser
 
 logger = logging.getLogger(__name__)
 
 class Lemmy:
     _known_communities = {}
     _requestor: Requestor
+    post: Post
+    community: Community
+    comment: Comment
+    site: Site
+    user: User
+    private_message: PrivateMessage
+    image: Image
+    mention: Mention
+    admin: Admin
 
     def __init__(self, api_base_url: str, raise_exceptions = False, request_timeout=3) -> None:
         self._requestor = Requestor(raise_exceptions, request_timeout)
@@ -79,6 +90,14 @@ def discover_community(self, community_name: str, search=SearchOption.Retry) ->
             self._known_communities[community_name] = community_id
             return community_id
 
+    def get_user(self, **kwargs) -> LemmyUser | None:
+        user_json = self.user.get(**kwargs)
+        if user_json is None:
+            return
+        user_dict = user_json['person_view']['person']
+        user_dict['is_admin'] = user_json['person_view']['is_admin']
+        return LemmyUser.from_dict(user_dict, self)
+        
     def search(
         self,
         q: str,

pythorhead/lemmy.py

@@ -3,7 +3,6 @@
 from pythorhead.requestor import Request, Requestor
 from pythorhead.types import SortType, ListingType, LanguageType
 
-
 class User:
     def __init__(self, _requestor: Requestor):
         self._requestor = _requestor
@@ -17,7 +16,8 @@ def get(
         limit: Optional[int] = None,
         community_id: Optional[int] = None,
         saved_only: Optional[bool] = None,
-    ) -> Optional[dict]:
+        return_user_object = False,
+    ) -> dict | None:
         """
         Get user details with various filters.
 
@@ -29,6 +29,7 @@ def get(
             limit (Optional[int], optional): Defaults to None.
             community_id (Optional[int], optional): Defaults to None.
             saved_only (Optional[bool], optional): Defaults to None.
+            return_user_object: (Optional[bool], optional): If true, returns a LemmyUser object, instead of the raw dict
         Returns:
             dict: user view
         """

pythorhead/user.py

@@ -0,0 +1,7 @@
+from datetime import datetime
+
+def json_serializer(obj):
+    if isinstance(obj, datetime):
+        return obj.isoformat()  # Convert datetime to ISO 8601 string
+    else:
+        return obj