scratchattach 2.1.15b0__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

{scratchattach/site → site}/user.py

@@ -1,13 +1,16 @@
 """User class"""
+
 from __future__ import annotations
 
 import json
 import random
 import re
 import string
+import warnings
+from typing import Union, cast, Optional, TypedDict
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from enum import Enum
-import warnings
 
 from typing_extensions import deprecated
 from bs4 import BeautifulSoup, Tag
@@ -26,29 +29,62 @@ from . import forum
 from . import comment
 from . import activity
 from . import classroom
+from . import typed_dicts
+from . import session
+
 
 class Rank(Enum):
     """
     Possible ranks in scratch
     """
+
     NEW_SCRATCHER = 0
     SCRATCHER = 1
     SCRATCH_TEAM = 2
 
+
+class _OcularStatusMeta(TypedDict):
+    updated: str
+    updatedBy: str
+
+
+class _OcularStatus(TypedDict):
+    _id: str
+    name: str
+    status: str
+    color: str
+    meta: _OcularStatusMeta
+
+
 class Verificator:
 
     def __init__(self, user: User, project_id: int):
-        self.project = user._make_linked_object("id", project_id, project.Project, exceptions.ProjectNotFound)
+        self.project = user._make_linked_object(
+            "id", project_id, project.Project, exceptions.ProjectNotFound
+        )
         self.projecturl = self.project.url
-        self.code = ''.join(random.choices(string.ascii_letters + string.digits, k=8))
+        self.code = "".join(random.choices(string.ascii_letters + string.digits, k=8))
         self.username = user.username
 
     def check(self) -> bool:
-        return bool(list(filter(lambda x : x.author_name == self.username and (x.content == self.code or x.content.startswith(self.code) or x.content.endswith(self.code)), self.project.comments())))
+        return bool(
+            list(
+                filter(
+                    lambda x: x.author_name == self.username
+                    and (
+                        x.content == self.code
+                        or x.content.startswith(self.code)
+                        or x.content.endswith(self.code)
+                    ),
+                    self.project.comments(),
+                )
+            )
+        )
 
-class User(BaseSiteComponent):
 
-    '''
+@dataclass
+class User(BaseSiteComponent[typed_dicts.UserDict]):
+    """
     Represents a Scratch user.
 
     Attributes:
@@ -68,76 +104,150 @@ class User(BaseSiteComponent):
     :.scratchteam: Retuns True if the user is in the Scratch team
 
     :.update(): Updates the attributes
-    '''
+    """
+
+    username: str = field(kw_only=True, default="")
+    join_date: str = field(kw_only=True, default="")
+    about_me: str = field(kw_only=True, default="")
+    wiwo: str = field(kw_only=True, default="")
+    country: str = field(kw_only=True, default="")
+    icon_url: str = field(kw_only=True, default="")
+    id: int = field(kw_only=True, default=0)
+    scratchteam: bool = field(kw_only=True, repr=False, default=False)
+    is_member: bool = field(kw_only=True, repr=False, default=False)
+    has_ears: bool = field(kw_only=True, repr=False, default=False)
+    _classroom: tuple[bool, Optional[classroom.Classroom]] = field(
+        init=False, default=(False, None)
+    )
+    _headers: dict[str, str] = field(init=False, default_factory=headers.copy)
+    _cookies: dict[str, str] = field(init=False, default_factory=dict)
+    _json_headers: dict[str, str] = field(init=False, default_factory=dict)
+    _session: Optional[session.Session] = field(kw_only=True, default=None)
 
     def __str__(self):
-        return str(self.username)
+        return f"-U {self.username}"
+
+    @property
+    def status(self) -> str:
+        return self.wiwo
+
+    @property
+    def bio(self) -> str:
+        return self.about_me
+
+    @property
+    def icon(self) -> bytes:
+        with requests.no_error_handling():
+            return requests.get(self.icon_url).content
+
+    @property
+    def name(self) -> str:
+        return self.username
 
-    def __init__(self, **entries):
+    def __post_init__(self):
 
         # Info on how the .update method has to fetch the data:
         self.update_function = requests.get
-        self.update_api = f"https://api.scratch.mit.edu/users/{entries['username']}"
-
-        # Set attributes every User object needs to have:
-        self._session = None
-        self.id = None
-        self.username = None
-        self.name = None
+        self.update_api = f"https://api.scratch.mit.edu/users/{self.username}"
 
         # cache value for classroom getter method (using @property)
         # first value is whether the cache has actually been set (because it can be None), second is the value itself
-        self._classroom: tuple[bool, classroom.Classroom | None] = False, None
-
-        # Update attributes from entries dict:
-        entries.setdefault("name", entries.get("username"))
-        self.__dict__.update(entries)
-
-        # Set alternative attributes:
-        if hasattr(self, "bio"):
-            self.about_me = self.bio
-        if hasattr(self, "status"):
-            self.wiwo = self.status
-        if hasattr(self, "name"):
-            self.username = self.name
+        # self._classroom
 
         # Headers and cookies:
-        if self._session is None:
-            self._headers :dict = headers
-            self._cookies = {}
-        else:
-            self._headers :dict = self._session._headers
-            self._cookies = self._session._cookies
+        if self._session is not None:
+            self._headers = self._session.get_headers()
+            self._cookies = self._session.get_cookies()
 
         # Headers for operations that require accept and Content-Type fields:
         self._json_headers = dict(self._headers)
         self._json_headers["accept"] = "application/json"
         self._json_headers["Content-Type"] = "application/json"
 
-    def _update_from_dict(self, data):
-        try: self.id = data["id"]
-        except KeyError: pass
-        try: self.username = data["username"]
-        except KeyError: pass
-        try: self.scratchteam = data["scratchteam"]
-        except KeyError: pass
-        try: self.join_date = data["history"]["joined"]
-        except KeyError: pass
-        try: self.about_me = data["profile"]["bio"]
-        except KeyError: pass
-        try: self.wiwo = data["profile"]["status"]
-        except KeyError: pass
-        try: self.country = data["profile"]["country"]
-        except KeyError: pass
-        try: self.icon_url = data["profile"]["images"]["90x90"]
-        except KeyError: pass
+    def _update_from_dict(self, data: Union[dict, typed_dicts.UserDict]):
+        data = cast(typed_dicts.UserDict, data)
+
+        self.id = data.get("id", self.id)
+        self.username = data.get("username", self.username)
+        self.scratchteam = data.get("scratchteam", self.scratchteam)
+        if history := data.get("history"):
+            self.join_date = history["joined"]
+
+        if profile := data.get("profile"):
+            self.about_me = profile["bio"]
+            self.wiwo = profile["status"]
+            self.country = profile["country"]
+            self.icon_url = profile["images"]["90x90"]
+            self.is_member = bool(profile.get("membership_label", False))
+            self.has_ears = bool(profile.get("membership_avatar_badge", False))
         return True
 
     def _assert_permission(self):
         self._assert_auth()
-        if self._session._username != self.username:
+        if self._session.username != self.username:
             raise exceptions.Unauthorized(
-                "You need to be authenticated as the profile owner to do this.")
+                "You need to be authenticated as the profile owner to do this."
+            )
+
+    @property
+    def url(self):
+        return f"https://scratch.mit.edu/users/{self.username}"
+
+    def __rich__(self):
+        from rich.panel import Panel
+        from rich.table import Table
+        from rich import box
+        from rich.markup import escape
+
+        featured_data = self.featured_data() or {}
+        ocular_data = self.ocular_status()
+        ocular = "No ocular status"
+
+        if status := ocular_data.get("status"):
+            color_str = ""
+            color_data = ocular_data.get("color")
+            if color_data is not None:
+                color_str = f"[{color_data}] ⬤ [/]"
+
+            ocular = f"[i]{escape(status)}[/]{color_str}"
+
+        _classroom = self.classroom
+        url = f"[link={self.url}]{escape(self.username)}[/]"
+
+        info = Table(box=box.SIMPLE)
+        info.add_column(url, overflow="fold")
+        info.add_column(f"#{self.id}", overflow="fold")
+
+        info.add_row("Joined", escape(self.join_date))
+        info.add_row("Country", escape(self.country))
+        info.add_row("Messages", str(self.message_count()))
+        info.add_row(
+            "Class", str(_classroom.title if _classroom is not None else "None")
+        )
+
+        desc = Table("Profile", ocular, box=box.SIMPLE)
+        desc.add_row("About me", escape(self.about_me))
+        desc.add_row("Wiwo", escape(self.wiwo))
+        desc.add_row(
+            escape(featured_data.get("label", "Featured Project")),
+            escape(str(self.connect_featured_project())),
+        )
+
+        ret = Table.grid(expand=True)
+
+        ret.add_column(ratio=1)
+        ret.add_column(ratio=3)
+        ret.add_row(Panel(info, title=url), Panel(desc, title="Description"))
+
+        return ret
+
+    def connect_featured_project(self) -> Optional[project.Project]:
+        data = self.featured_data() or {}
+        if pid := data.get("id"):
+            return self._session.connect_project(int(pid))
+        if projs := self.projects(limit=1):
+            return projs[0]
+        return None
 
     @property
     def classroom(self) -> classroom.Classroom | None:
@@ -151,48 +261,58 @@ class User(BaseSiteComponent):
             soup = BeautifulSoup(resp.text, "html.parser")
 
             details = soup.find("p", {"class": "profile-details"})
+            if details is None:
+                # No details, e.g. if the user is banned
+                return None
+
             assert isinstance(details, Tag)
 
-            class_name, class_id, is_closed = None, 0, False
+            class_name, class_id, is_closed = None, None, False
             for a in details.find_all("a"):
                 if not isinstance(a, Tag):
                     continue
                 href = str(a.get("href"))
                 if re.match(r"/classes/\d*/", href):
-                    class_name = a.text.strip()[len("Student of: "):]
-                    is_closed = class_name.endswith("\n            (ended)") # as this has a \n, we can be sure
+                    class_name = a.text.strip()[len("Student of: ") :]
+                    is_closed = bool(
+                        re.search(r"\n *\(ended\)", class_name)
+                    )  # as this has a \n, we can be sure
                     if is_closed:
-                        class_name = class_name[:-7].strip()
+                        class_name = re.sub(r"\n *\(ended\)", "", class_name).strip()
 
-                    class_id = int(href.split('/')[2])
+                    class_id = int(href.split("/")[2])
                     break
 
             if class_name:
                 self._classroom = True, classroom.Classroom(
                     _session=self._session,
-                    id=class_id,
+                    id=class_id or 0,
                     title=class_name,
-                    is_closed=is_closed
+                    is_closed=is_closed,
                 )
             else:
                 self._classroom = True, None
 
         return self._classroom[1]
 
-    def does_exist(self):
+    def does_exist(self) -> Optional[bool]:
         """
         Returns:
             boolean : True if the user exists, False if the user is deleted, None if an error occured
         """
         with requests.no_error_handling():
-            status_code = requests.get(f"https://scratch.mit.edu/users/{self.username}/").status_code
-        if status_code == 200:
-            return True
-        elif status_code == 404:
-            return False
+            status_code = requests.get(
+                f"https://scratch.mit.edu/users/{self.username}/"
+            ).status_code
+            if status_code == 200:
+                return True
+            elif status_code == 404:
+                return False
+
+        return None
 
     # Will maybe be deprecated later, but for now still has its own purpose.
-    #@deprecated("This function is partially deprecated. Use user.rank() instead.")
+    # @deprecated("This function is partially deprecated. Use user.rank() instead.")
     def is_new_scratcher(self):
         """
         Returns:
@@ -200,8 +320,10 @@ class User(BaseSiteComponent):
         """
         try:
             with requests.no_error_handling():
-                res = requests.get(f"https://scratch.mit.edu/users/{self.username}/").text
-                group = res[res.rindex('<span class="group">'):][:70]
+                res = requests.get(
+                    f"https://scratch.mit.edu/users/{self.username}/"
+                ).text
+                group = res[res.rindex('<span class="group">') :][:70]
                 return "new scratcher" in group.lower()
 
         except Exception as e:
@@ -209,8 +331,14 @@ class User(BaseSiteComponent):
             return None
 
     def message_count(self):
-
-        return json.loads(requests.get(f"https://api.scratch.mit.edu/users/{self.username}/messages/count/?cachebust={random.randint(0,10000)}", headers = {'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.3c6 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36',}).text)["count"]
+        return json.loads(
+            requests.get(
+                f"https://api.scratch.mit.edu/users/{self.username}/messages/count/?cachebust={random.randint(0,10000)}",
+                headers={
+                    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.3c6 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
+                },
+            ).text
+        )["count"]
 
     def featured_data(self):
         """
@@ -218,35 +346,69 @@ class User(BaseSiteComponent):
             dict: Gets info on the user's featured project and featured label (like "Featured project", "My favorite things", etc.)
         """
         try:
-            response = json.loads(requests.get(f"https://scratch.mit.edu/site-api/users/all/{self.username}/").text)
+            response = requests.get(
+                f"https://scratch.mit.edu/site-api/users/all/{self.username}/"
+            ).json()
             return {
-                "label":response["featured_project_label_name"],
-                "project":
-                        dict(
-                            id=str(response["featured_project_data"]["id"]),
-                            author=response["featured_project_data"]["creator"],
-                            thumbnail_url="https://"+response["featured_project_data"]["thumbnail_url"][2:],
-                            title=response["featured_project_data"]["title"]
-                        )
-                    }
+                "label": response["featured_project_label_name"],
+                "project": dict(
+                    id=str(response["featured_project_data"]["id"]),
+                    author=response["featured_project_data"]["creator"],
+                    thumbnail_url="https://"
+                    + response["featured_project_data"]["thumbnail_url"][2:],
+                    title=response["featured_project_data"]["title"],
+                ),
+            }
         except Exception:
             return None
 
+    def unfollowers(self) -> list[User]:
+        """
+        Get all unfollowers by comparing API response and HTML response.
+        NOTE: This method can take a long time to run.
+
+        Based on https://juegostrower.github.io/unfollowers/
+        """
+        follower_count = self.follower_count()
+
+        # regular followers
+        usernames = []
+        for i in range(1, 2 + follower_count // 60):
+            with requests.no_error_handling():
+                resp = requests.get(
+                    f"https://scratch.mit.edu/users/{self.username}/followers/",
+                    params={"page": i},
+                )
+            soup = BeautifulSoup(resp.text, "html.parser")
+            usernames.extend(span.text.strip() for span in soup.select("span.title"))
+
+        # api response contains all-time followers, including deleted and unfollowed
+        unfollowers = []
+        for offset in range(0, follower_count, 40):
+            unfollowers.extend(
+                user
+                for user in self.followers(offset=offset, limit=40)
+                if user.username not in usernames
+            )
+
+        return unfollowers
+
+    def unfollower_usernames(self) -> list[str]:
+        return [user.username for user in self.unfollowers()]
+
     def follower_count(self):
-        # follower count
         with requests.no_error_handling():
             text = requests.get(
                 f"https://scratch.mit.edu/users/{self.username}/followers/",
-                headers = self._headers
+                headers=self._headers,
             ).text
             return commons.webscrape_count(text, "Followers (", ")")
 
     def following_count(self):
-        # following count
         with requests.no_error_handling():
             text = requests.get(
                 f"https://scratch.mit.edu/users/{self.username}/following/",
-                headers = self._headers
+                headers=self._headers,
             ).text
             return commons.webscrape_count(text, "Following (", ")")
 
@@ -256,7 +418,10 @@ class User(BaseSiteComponent):
             list<scratchattach.user.User>: The user's followers as list of scratchattach.user.User objects
         """
         response = commons.api_iterative(
-            f"https://api.scratch.mit.edu/users/{self.username}/followers/", limit=limit, offset=offset)
+            f"https://api.scratch.mit.edu/users/{self.username}/followers/",
+            limit=limit,
+            offset=offset,
+        )
         return commons.parse_object_list(response, User, self._session, "username")
 
     def follower_names(self, *, limit=40, offset=0):
@@ -272,7 +437,10 @@ class User(BaseSiteComponent):
             list<scratchattach.user.User>: The users that the user is following as list of scratchattach.user.User objects
         """
         response = commons.api_iterative(
-            f"https://api.scratch.mit.edu/users/{self.username}/following/", limit=limit, offset=offset)
+            f"https://api.scratch.mit.edu/users/{self.username}/following/",
+            limit=limit,
+            offset=offset,
+        )
         return commons.parse_object_list(response, User, self._session, "username")
 
     def following_names(self, *, limit=40, offset=0):
@@ -330,7 +498,7 @@ class User(BaseSiteComponent):
         with requests.no_error_handling():
             text = requests.get(
                 f"https://scratch.mit.edu/users/{self.username}/projects/",
-                headers = self._headers
+                headers=self._headers,
             ).text
             return commons.webscrape_count(text, "Shared Projects (", ")")
 
@@ -338,7 +506,7 @@ class User(BaseSiteComponent):
         with requests.no_error_handling():
             text = requests.get(
                 f"https://scratch.mit.edu/users/{self.username}/studios/",
-                headers = self._headers
+                headers=self._headers,
             ).text
             return commons.webscrape_count(text, "Studios I Curate (", ")")
 
@@ -346,16 +514,19 @@ class User(BaseSiteComponent):
         with requests.no_error_handling():
             text = requests.get(
                 f"https://scratch.mit.edu/users/{self.username}/studios_following/",
-                headers = self._headers
+                headers=self._headers,
             ).text
             return commons.webscrape_count(text, "Studios I Follow (", ")")
 
-    def studios(self, *, limit=40, offset=0):
+    def studios(self, *, limit=40, offset=0) -> list[studio.Studio]:
         _studios = commons.api_iterative(
-            f"https://api.scratch.mit.edu/users/{self.username}/studios/curate", limit=limit, offset=offset)
+            f"https://api.scratch.mit.edu/users/{self.username}/studios/curate",
+            limit=limit,
+            offset=offset,
+        )
         studios = []
         for studio_dict in _studios:
-            _studio = studio.Studio(_session = self._session, id = studio_dict["id"])
+            _studio = studio.Studio(_session=self._session, id=studio_dict["id"])
             _studio._update_from_dict(studio_dict)
             studios.append(_studio)
         return studios
@@ -366,12 +537,18 @@ class User(BaseSiteComponent):
             list<projects.projects.Project>: The user's shared projects
         """
         _projects = commons.api_iterative(
-            f"https://api.scratch.mit.edu/users/{self.username}/projects/", limit=limit, offset=offset, _headers= self._headers)
+            f"https://api.scratch.mit.edu/users/{self.username}/projects/",
+            limit=limit,
+            offset=offset,
+            _headers=self._headers,
+        )
         for p in _projects:
-            p["author"] = {"username":self.username}
+            p["author"] = {"username": self.username}
         return commons.parse_object_list(_projects, project.Project, self._session)
 
-    def loves(self, *, limit=40, offset=0, get_full_project: bool = False) -> list[project.Project]:
+    def loves(
+        self, *, limit=40, offset=0, get_full_project: bool = False
+    ) -> list[project.Project]:
         """
         Returns:
             list<projects.projects.Project>: The user's loved projects
@@ -391,8 +568,7 @@ class User(BaseSiteComponent):
         # So the page number for this is 1 + (offset + limit - 1) // 40
 
         # But this is a range so we have to add another 1 for the second argument
-        pages = range(1 + offset // 40,
-                      2 + (offset + limit - 1) // 40)
+        pages = range(1 + offset // 40, 2 + (offset + limit - 1) // 40)
         _projects = []
 
         for page in pages:
@@ -400,13 +576,13 @@ class User(BaseSiteComponent):
             first_idx = (page - 1) * 40
 
             with requests.no_error_handling():
-                page_content = requests.get(f"https://scratch.mit.edu/projects/all/{self.username}/loves/"
-                                            f"?page={page}", headers=self._headers).content
+                page_content = requests.get(
+                    f"https://scratch.mit.edu/projects/all/{self.username}/loves/"
+                    f"?page={page}",
+                    headers=self._headers,
+                ).content
 
-            soup = BeautifulSoup(
-                page_content,
-                "html.parser"
-            )
+            soup = BeautifulSoup(page_content, "html.parser")
 
             # We need to check if we are out of bounds
             # If we are, we can jump out early
@@ -424,7 +600,8 @@ class User(BaseSiteComponent):
 
             # Each project element is a list item with the class name 'project thumb item' so we can just use that
             for i, project_element in enumerate(
-                    soup.find_all("li", {"class": "project thumb item"})):
+                soup.find_all("li", {"class": "project thumb item"})
+            ):
                 # Remember we only want certain projects:
                 # The current project idx = first_idx + i
                 # We want to start at {offset} and end at {offset + limit}
@@ -451,26 +628,27 @@ class User(BaseSiteComponent):
                     assert isinstance(first_anchor, Tag)
                     assert isinstance(second_anchor, Tag)
                     assert isinstance(third_anchor, Tag)
-                    project_id = commons.webscrape_count(first_anchor.attrs["href"],
-                                                         "/projects/", "/")
+                    project_id = commons.webscrape_count(
+                        first_anchor.attrs["href"], "/projects/", "/"
+                    )
                     title = second_anchor.contents[0]
                     author = third_anchor.contents[0]
 
                     # Instantiating a project with the properties that we know
                     # This may cause issues (see below)
-                    _project = project.Project(id=project_id,
-                                               _session=self._session,
-                                               title=title,
-                                               author_name=author,
-                                               url=f"https://scratch.mit.edu/projects/{project_id}/")
+                    _project = project.Project(
+                        id=project_id,
+                        _session=self._session,
+                        title=title,
+                        author_name=author,
+                        url=f"https://scratch.mit.edu/projects/{project_id}/",
+                    )
                     if get_full_project:
                         # Put this under an if statement since making api requests for every single
                         # project will cause the function to take a lot longer
                         _project.update()
 
-                    _projects.append(
-                        _project
-                    )
+                    _projects.append(_project)
 
         return _projects
 
@@ -478,7 +656,7 @@ class User(BaseSiteComponent):
         with requests.no_error_handling():
             text = requests.get(
                 f"https://scratch.mit.edu/projects/all/{self.username}/loves/",
-                headers=self._headers
+                headers=self._headers,
             ).text
 
         # If there are no loved projects, then Scratch doesn't actually display the number - so we have to catch this
@@ -496,25 +674,47 @@ class User(BaseSiteComponent):
             list<projects.projects.Project>: The user's favorite projects
         """
         _projects = commons.api_iterative(
-            f"https://api.scratch.mit.edu/users/{self.username}/favorites/", limit=limit, offset=offset, _headers= self._headers)
+            f"https://api.scratch.mit.edu/users/{self.username}/favorites/",
+            limit=limit,
+            offset=offset,
+            _headers=self._headers,
+        )
         return commons.parse_object_list(_projects, project.Project, self._session)
 
     def favorites_count(self):
         with requests.no_error_handling():
             text = requests.get(
                 f"https://scratch.mit.edu/users/{self.username}/favorites/",
-                headers=self._headers
+                headers=self._headers,
             ).text
         return commons.webscrape_count(text, "Favorites (", ")")
 
+    def has_badge(self) -> bool:
+        """
+        Returns:
+            bool: Whether the user has a scratch membership badge on their profile (located next to the follow button)
+        """
+        with requests.no_error_handling():
+            resp = requests.get(self.url)
+            soup = BeautifulSoup(resp.text, "html.parser")
+            head = soup.find("div", {"class": "box-head"})
+            if not head:
+                return False
+            for child in head.children:
+                if child.name == "img":
+                    if "membership-badge.svg" in child["src"]:
+                        return True
+        return False
+
     def toggle_commenting(self):
         """
         You can only use this function if this object was created using :meth:`scratchattach.session.Session.connect_user`
         """
         self._assert_permission()
-        requests.post(f"https://scratch.mit.edu/site-api/comments/user/{self.username}/toggle-comments/",
-            headers = headers,
-            cookies = self._cookies
+        requests.post(
+            f"https://scratch.mit.edu/site-api/comments/user/{self.username}/toggle-comments/",
+            headers=headers,
+            cookies=self._cookies,
         )
 
     def viewed_projects(self, limit=24, offset=0):
@@ -526,7 +726,11 @@ class User(BaseSiteComponent):
         """
         self._assert_permission()
         _projects = commons.api_iterative(
-            f"https://api.scratch.mit.edu/users/{self.username}/projects/recentlyviewed", limit=limit, offset=offset, _headers= self._headers)
+            f"https://api.scratch.mit.edu/users/{self.username}/projects/recentlyviewed",
+            limit=limit,
+            offset=offset,
+            _headers=self._headers,
+        )
         return commons.parse_object_list(_projects, project.Project, self._session)
 
     def set_pfp(self, image: bytes):
@@ -539,7 +743,8 @@ class User(BaseSiteComponent):
             f"https://scratch.mit.edu/site-api/users/all/{self.username}/",
             headers=self._headers,
             cookies=self._cookies,
-            files={"file": image})
+            files={"file": image},
+        )
 
     def set_bio(self, text):
         """
@@ -551,7 +756,8 @@ class User(BaseSiteComponent):
             f"https://scratch.mit.edu/site-api/users/all/{self.username}/",
             headers=self._json_headers,
             cookies=self._cookies,
-            json={"bio": text})
+            json={"bio": text},
+        )
 
     def set_wiwo(self, text):
         """
@@ -563,7 +769,8 @@ class User(BaseSiteComponent):
             f"https://scratch.mit.edu/site-api/users/all/{self.username}/",
             headers=self._json_headers,
             cookies=self._cookies,
-            json={"status": text})
+            json={"status": text},
+        )
 
     def set_featured(self, project_id, *, label=""):
         """
@@ -580,7 +787,7 @@ class User(BaseSiteComponent):
             f"https://scratch.mit.edu/site-api/users/all/{self.username}/",
             headers=self._json_headers,
             cookies=self._cookies,
-            json={"featured_project": int(project_id), "featured_project_label": label}
+            json={"featured_project": int(project_id), "featured_project_label": label},
         )
 
     def set_forum_signature(self, text):
@@ -589,38 +796,43 @@ class User(BaseSiteComponent):
         """
         self._assert_permission()
         headers = {
-            'accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7',
-            'content-type': 'application/x-www-form-urlencoded',
-            'origin': 'https://scratch.mit.edu',
-            'referer': 'https://scratch.mit.edu/discuss/settings/TimMcCool/',
-            'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36',
+            "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
+            "content-type": "application/x-www-form-urlencoded",
+            "origin": "https://scratch.mit.edu",
+            "referer": "https://scratch.mit.edu/discuss/settings/TimMcCool/",
+            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
         }
         data = {
-            'csrfmiddlewaretoken': 'a',
-            'signature': text,
-            'update': '',
+            "csrfmiddlewaretoken": "a",
+            "signature": text,
+            "update": "",
         }
-        response = requests.post(f'https://scratch.mit.edu/discuss/settings/{self.username}/', cookies=self._cookies, headers=headers, data=data)
+        response = requests.post(
+            f"https://scratch.mit.edu/discuss/settings/{self.username}/",
+            cookies=self._cookies,
+            headers=headers,
+            data=data,
+        )
 
     def post_comment(self, content, *, parent_id="", commentee_id=""):
         """
         Posts a comment on the user's profile. You can only use this function if this object was created using :meth:`scratchattach.session.Session.connect_user`
 
         Args:
-            content: Content of the comment that should be posted
+            :param content: Content of the comment that should be posted
 
         Keyword Arguments:
-            parent_id: ID of the comment you want to reply to. If you don't want to mention a user, don't put the argument.
-            commentee_id: ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don't want to mention a user, don't put the argument.
+            :param commentee_id: ID of the comment you want to reply to. If you don't want to mention a user, don't put the argument.
+            :param parent_id: ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don't want to mention a user, don't put the argument.
 
         Returns:
             scratchattach.comment.Comment: An object representing the created comment.
         """
         self._assert_auth()
         data = {
-                "commentee_id": commentee_id,
-                "content": str(content),
-                "parent_id": parent_id,
+            "commentee_id": commentee_id,
+            "content": str(content),
+            "parent_id": parent_id,
         }
         r = requests.post(
             f"https://scratch.mit.edu/site-api/comments/user/{self.username}/add/",
@@ -634,30 +846,55 @@ class User(BaseSiteComponent):
             else:
                 raise exceptions.CommentPostFailure(r.text)
 
+        text = r.text
         try:
-            text = r.text
             data = {
-                'id': text.split('<div id="comments-')[1].split('" class="comment')[0],
-                'author': {"username": text.split('" data-comment-user="')[1].split('"><img class')[0]},
-                'content': text.split('<div class="content">')[1].split('</div>')[0].strip(),
-                'reply_count': 0,
-                'cached_replies': []
+                "id": text.split('<div id="comments-')[1].split('" class="comment')[0],
+                "author": {
+                    "username": text.split('" data-comment-user="')[1].split(
+                        '"><img class'
+                    )[0]
+                },
+                "content": text.split('<div class="content">')[1]
+                .split("</div>")[0]
+                .strip(),
+                "reply_count": 0,
+                "cached_replies": [],
             }
-            _comment = comment.Comment(source="profile", parent_id=None if parent_id=="" else parent_id, commentee_id=commentee_id, source_id=self.username, id=data["id"], _session = self._session, datetime = datetime.now())
+            _comment = comment.Comment(
+                source=comment.CommentSource.USER_PROFILE,
+                parent_id=None if parent_id == "" else parent_id,
+                commentee_id=commentee_id,
+                source_id=self.username,
+                id=data["id"],
+                _session=self._session,
+                datetime=datetime.now(),
+            )
             _comment._update_from_dict(data)
             return _comment
-        except Exception:
+        except Exception as e:
             if '{"error": "isFlood"}' in text:
-                raise(exceptions.CommentPostFailure(
-                    "You are being rate-limited for running this operation too often. Implement a cooldown of about 10 seconds."))
+                raise (
+                    exceptions.CommentPostFailure(
+                        "You are being rate-limited for running this operation too often. Implement a cooldown of about 10 seconds."
+                    )
+                ) from e
             elif '<script id="error-data" type="application/json">' in text:
-                raw_error_data = text.split('<script id="error-data" type="application/json">')[1].split('</script>')[0]
+                raw_error_data = text.split(
+                    '<script id="error-data" type="application/json">'
+                )[1].split("</script>")[0]
                 error_data = json.loads(raw_error_data)
-                expires = error_data['mute_status']['muteExpiresAt']
+                expires = error_data["mute_status"]["muteExpiresAt"]
                 expires = datetime.fromtimestamp(expires, timezone.utc)
-                raise(exceptions.CommentPostFailure(f"You have been muted. Mute expires on {expires}"))
+                raise (
+                    exceptions.CommentPostFailure(
+                        f"You have been muted. Mute expires on {expires}"
+                    )
+                ) from e
             else:
-                raise(exceptions.FetchError(f"Couldn't parse API response: {r.text!r}"))
+                raise (
+                    exceptions.FetchError(f"Couldn't parse API response: {r.text!r}")
+                ) from e
 
     def reply_comment(self, content, *, parent_id, commentee_id=""):
         """
@@ -669,13 +906,15 @@ class User(BaseSiteComponent):
             Therefore, parent_id should be the comment id of a top level comment.
 
         Args:
-            content: Content of the comment that should be posted
+            :param content: Content of the comment that should be posted
 
         Keyword Arguments:
-            parent_id: ID of the comment you want to reply to
-            commentee_id: ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don't want to mention a user, don't put the argument.
+            :param parent_id: ID of the comment you want to reply to
+            :param commentee_id: ID of the user that will be mentioned in your comment and will receive a message about your comment. If you don't want to mention a user, don't put the argument.
         """
-        return self.post_comment(content, parent_id=parent_id, commentee_id=commentee_id)
+        return self.post_comment(
+            content, parent_id=parent_id, commentee_id=commentee_id
+        )
 
     def activity(self, *, limit=1000):
         """
@@ -683,27 +922,32 @@ class User(BaseSiteComponent):
             list<scratchattach.Activity>: The user's activity data as parsed list of scratchattach.activity.Activity objects
         """
         with requests.no_error_handling():
-            soup = BeautifulSoup(requests.get(f"https://scratch.mit.edu/messages/ajax/user-activity/?user={self.username}&max={limit}").text, 'html.parser')
+            soup = BeautifulSoup(
+                requests.get(
+                    f"https://scratch.mit.edu/messages/ajax/user-activity/?user={self.username}&max={limit}"
+                ).text,
+                "html.parser",
+            )
 
         activities = []
         source = soup.find_all("li")
 
         for data in source:
-            _activity = activity.Activity(_session = self._session, raw=data)
+            _activity = activity.Activity(_session=self._session, raw=data)
             _activity._update_from_html(data)
             activities.append(_activity)
 
         return activities
 
-
     def activity_html(self, *, limit=1000):
         """
         Returns:
             str: The raw user activity HTML data
         """
         with requests.no_error_handling():
-            return requests.get(f"https://scratch.mit.edu/messages/ajax/user-activity/?user={self.username}&max={limit}").text
-
+            return requests.get(
+                f"https://scratch.mit.edu/messages/ajax/user-activity/?user={self.username}&max={limit}"
+            ).text
 
     def follow(self):
         """
@@ -712,8 +956,8 @@ class User(BaseSiteComponent):
         self._assert_auth()
         requests.put(
             f"https://scratch.mit.edu/site-api/users/followers/{self.username}/add/?usernames={self._session._username}",
-            headers = headers,
-            cookies = self._cookies,
+            headers=headers,
+            cookies=self._cookies,
         )
 
     def unfollow(self):
@@ -723,8 +967,8 @@ class User(BaseSiteComponent):
         self._assert_auth()
         requests.put(
             f"https://scratch.mit.edu/site-api/users/followers/{self.username}/remove/?usernames={self._session._username}",
-            headers = headers,
-            cookies = self._cookies,
+            headers=headers,
+            cookies=self._cookies,
         )
 
     def delete_comment(self, *, comment_id):
@@ -735,12 +979,13 @@ class User(BaseSiteComponent):
             comment_id: The id of the comment that should be deleted
         """
         self._assert_permission()
-        return requests.post(
-            f"https://scratch.mit.edu/site-api/comments/user/{self.username}/del/",
-            headers = headers,
-            cookies = self._cookies,
-            data = json.dumps({"id":str(comment_id)})
-        )
+        with requests.no_error_handling():
+            return requests.post(
+                f"https://scratch.mit.edu/site-api/comments/user/{self.username}/del/",
+                headers=headers,
+                cookies=self._cookies,
+                data=json.dumps({"id": str(comment_id)}),
+            )
 
     def report_comment(self, *, comment_id):
         """
@@ -752,12 +997,12 @@ class User(BaseSiteComponent):
         self._assert_auth()
         return requests.post(
             f"https://scratch.mit.edu/site-api/comments/user/{self.username}/rep/",
-            headers = headers,
-            cookies = self._cookies,
-            data = json.dumps({"id":str(comment_id)})
+            headers=headers,
+            cookies=self._cookies,
+            data=json.dumps({"id": str(comment_id)}),
         )
 
-    def comments(self, *, page=1, limit=None):
+    def comments(self, *, page=1, limit=None) -> list[comment.Comment]:
         """
         Returns the comments posted on the user's profile (with replies).
 
@@ -779,21 +1024,25 @@ class User(BaseSiteComponent):
         _comments = soup.find_all("li", {"class": "top-level-reply"})
 
         if len(_comments) == 0:
-            return None
+            return []
 
         for entity in _comments:
-            comment_id = entity.find("div", {"class": "comment"})['data-comment-id']
-            user = entity.find("a", {"id": "comment-user"})['data-comment-user']
+            comment_id = entity.find("div", {"class": "comment"})["data-comment-id"]
+            user = entity.find("a", {"id": "comment-user"})["data-comment-user"]
             content = str(entity.find("div", {"class": "content"}).text).strip()
-            time = entity.find("span", {"class": "time"})['title']
+            time = entity.find("span", {"class": "time"})["title"]
 
             main_comment = {
-                'id': comment_id,
-                'author': {"username":user},
-                'content': content,
-                'datetime_created': time,
+                "id": comment_id,
+                "author": {"username": user},
+                "content": content,
+                "datetime_created": time,
             }
-            _comment = comment.Comment(source="profile", source_id=self.username, _session = self._session)
+            _comment = comment.Comment(
+                source=comment.CommentSource.USER_PROFILE,
+                source_id=self.username,
+                _session=self._session,
+            )
             _comment._update_from_dict(main_comment)
 
             ALL_REPLIES = []
@@ -803,20 +1052,31 @@ class User(BaseSiteComponent):
             else:
                 hasReplies = False
             for reply in replies:
-                r_comment_id = reply.find("div", {"class": "comment"})['data-comment-id']
-                r_user = reply.find("a", {"id": "comment-user"})['data-comment-user']
-                r_content = str(reply.find("div", {"class": "content"}).text).strip().replace("\n", "").replace(
-                    "                    ", " ")
-                r_time = reply.find("span", {"class": "time"})['title']
+                r_comment_id = reply.find("div", {"class": "comment"})[
+                    "data-comment-id"
+                ]
+                r_user = reply.find("a", {"id": "comment-user"})["data-comment-user"]
+                r_content = (
+                    str(reply.find("div", {"class": "content"}).text)
+                    .strip()
+                    .replace("\n", "")
+                    .replace("                    ", " ")
+                )
+                r_time = reply.find("span", {"class": "time"})["title"]
                 reply_data = {
-                    'id': r_comment_id,
-                    'author':{'username': r_user},
-                    'content': r_content,
-                    'datetime_created': r_time,
-                    "parent_id" : comment_id,
-                    "cached_parent_comment" : _comment,
+                    "id": r_comment_id,
+                    "author": {"username": r_user},
+                    "content": r_content,
+                    "datetime_created": r_time,
+                    "parent_id": comment_id,
+                    "cached_parent_comment": _comment,
                 }
-                _r_comment = comment.Comment(source="profile", source_id=self.username, _session = self._session, cached_parent_comment=_comment)
+                _r_comment = comment.Comment(
+                    source=comment.CommentSource.USER_PROFILE,
+                    source_id=self.username,
+                    _session=self._session,
+                    cached_parent_comment=_comment,
+                )
                 _r_comment._update_from_dict(reply_data)
                 ALL_REPLIES.append(_r_comment)
 
@@ -840,9 +1100,14 @@ class User(BaseSiteComponent):
         page = 1
         page_content = self.comments(page=page)
         while page_content != []:
-            results = list(filter(lambda x : str(x.id) == str(comment_id), page_content))
+            results = list(filter(lambda x: str(x.id) == str(comment_id), page_content))
             if results == []:
-                results = list(filter(lambda x : str(x.id) == str(comment_id), [item for x in page_content for item in x.cached_replies]))
+                results = list(
+                    filter(
+                        lambda x: str(x.id) == str(comment_id),
+                        [item for x in page_content for item in x.cached_replies],
+                    )
+                )
                 if results != []:
                     return results[0]
             else:
@@ -854,6 +1119,7 @@ class User(BaseSiteComponent):
     def message_events(self):
         return message_events.MessageEvents(self)
 
+    @deprecated("This method is deprecated because ScratchDB is down indefinitely.")
     def stats(self):
         """
         Gets information about the user's stats. Fetched from ScratchDB.
@@ -864,16 +1130,25 @@ class User(BaseSiteComponent):
         Returns:
             dict: A dict containing the user's stats. If the stats aren't available, all values will be -1.
         """
-        print("Warning: ScratchDB is down indefinitely, therefore this method is deprecated.")
         try:
-            stats= requests.get(
+            stats = requests.get(
                 f"https://scratchdb.lefty.one/v3/user/info/{self.username}"
             ).json()["statistics"]
             stats.pop("ranks")
         except Exception:
-            stats = {"loves":-1,"favorites":-1,"comments":-1,"views":-1,"followers":-1,"following":-1}
+            stats = {
+                "loves": -1,
+                "favorites": -1,
+                "comments": -1,
+                "views": -1,
+                "followers": -1,
+                "following": -1,
+            }
         return stats
 
+    @deprecated(
+        "Warning: ScratchDB is down indefinitely, therefore this method is deprecated."
+    )
     def ranks(self):
         """
         Gets information about the user's ranks. Fetched from ScratchDB.
@@ -884,22 +1159,38 @@ class User(BaseSiteComponent):
         Returns:
             dict: A dict containing the user's ranks. If the ranks aren't available, all values will be -1.
         """
-        print("Warning: ScratchDB is down indefinitely, therefore this method is deprecated.")
         try:
             return requests.get(
                 f"https://scratchdb.lefty.one/v3/user/info/{self.username}"
             ).json()["statistics"]["ranks"]
         except Exception:
-            return {"country":{"loves":0,"favorites":0,"comments":0,"views":0,"followers":0,"following":0},"loves":0,"favorites":0,"comments":0,"views":0,"followers":0,"following":0}
+            return {
+                "country": {
+                    "loves": 0,
+                    "favorites": 0,
+                    "comments": 0,
+                    "views": 0,
+                    "followers": 0,
+                    "following": 0,
+                },
+                "loves": 0,
+                "favorites": 0,
+                "comments": 0,
+                "views": 0,
+                "followers": 0,
+                "following": 0,
+            }
 
-    def ocular_status(self):
+    def ocular_status(self) -> _OcularStatus:
         """
         Gets information about the user's ocular status. Ocular is a website developed by jeffalo: https://ocular.jeffalo.net/
 
         Returns:
             dict
         """
-        return requests.get(f"https://my-ocular.jeffalo.net/api/user/{self.username}").json()
+        return requests.get(
+            f"https://my-ocular.jeffalo.net/api/user/{self.username}"
+        ).json()
 
     def verify_identity(self, *, verification_project_id=395330233):
         """
@@ -917,26 +1208,25 @@ class User(BaseSiteComponent):
         v = Verificator(self, verification_project_id)
         return v
 
-    def rank(self):
+    def rank(self) -> Rank:
         """
         Finds the rank of the user.
+        Returns a member of the Rank enum: either Rank.NEW_SCRATCHER, Rank.SCRATCHER, or Rank.SCRATCH_TEAM.
         May replace user.scratchteam and user.is_new_scratcher in the future.
         """
 
         if self.is_new_scratcher():
             return Rank.NEW_SCRATCHER
-            # Is New Scratcher
-        
+
         if not self.scratchteam:
             return Rank.SCRATCHER
-            # Is Scratcher
 
         return Rank.SCRATCH_TEAM
-        # Is Scratch Team member
 
 
 # ------ #
 
+
 def get_user(username) -> User:
     """
     Gets a user without logging in.
@@ -952,5 +1242,11 @@ def get_user(username) -> User:
 
         If you want to use these, get the user with :meth:`scratchattach.session.Session.connect_user` instead.
     """
-    print("Warning: For methods that require authentication, use session.connect_user instead of get_user")
+    warnings.warn(
+        "Warning: For methods that require authentication, use session.connect_user instead of get_user.\n"
+        "To ignore this warning, use warnings.filterwarnings('ignore', category=scratchattach.UserAuthenticationWarning).\n"
+        "To ignore all warnings of the type GetAuthenticationWarning, which includes this warning, use "
+        "`warnings.filterwarnings('ignore', category=scratchattach.GetAuthenticationWarning)`.",
+        exceptions.UserAuthenticationWarning,
+    )
     return commons._get_object("username", username, User, exceptions.UserNotFound)